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Description 



Database System with Methodology for 
Providing Stored Procedures as Web 
Services 

Copyright Statement 

[0001] a portion of the disclosure of this patent document con- 
tains material which is subject to copyright protection. 
The copyright owner has no objection to the facsimile re- 
production by anyone of the patent document or the 
patent disclosure as it appears in the Patent and Trade- 
mark Office patent file or records, but otherwise reserves 
all copyright rights whatsoever. 
Appendix Data 

[0002] Computer Program Listing Appendix under Sec. 1.52(e): 
This application includes a transmittal under 37 C.F.R. 
Sec. 1.52(e) of a Computer Program Listing Appendix. The 
Appendix, which comprises text file(s) that are IBM-PC 
machine and Microsoft Windows Operating System com- 



patible, includes the below-listed file(s). All of the mate- 
rial disclosed in the Computer Program Listing Appendix 
can be found at the U.S. Patent and Trademark Office 
archives and is hereby incorporated by reference into the 
present application. 
[0003] object Description: SourceCode.txt, size: 53124 Bytes, 
created: 04/21/2004 12:49:26 PM; Object ID: File No. 1; 
Object Contents: Source code. 
Background of Invention 

[0004] 1. Field of the Invention 

[0005] The present invention relates generally to data processing 
environments and, more particularly, to a database system 
providing stored procedures as Web services. 

[0006] 2. Description of the Background Art 

[0007] Computers are very powerful tools for storing and provid- 
ing access to vast amounts of information. Computer 
databases are a common mechanism for storing informa- 
tion on computer systems while providing easy access to 
users. A typical database is an organized collection of re- 
lated information stored as "records" having "fields" of in- 
formation. As an example, a database of employees may 
have a record for each employee where each record con- 



tains fields designating specifics about the employee, 
such as name, home address, salary, and the like. 

[0008] Between the actual physical database itself (i.e., the data 
actually stored on a storage device) and the users of the 
system, a database management system or DBMS is typi- 
cally provided as a software cushion or layer. In essence, 
the DBMS shields the database user from knowing or even 
caring about the underlying hardware-level details. Typi- 
cally, all requests from users for access to the data are 
processed by the DBMS. For example, information may be 
added or removed from data files, information retrieved 
from or updated in such files, and so forth, all without 
user knowledge of the underlying system implementation. 
In this manner, the DBMS provides users with a conceptual 
view of the database that is removed from the hardware 
level. The general construction and operation of database 
management systems is well known in the art. See e.g., 
Date, C, "An Introduction to Database Systems, Seventh 
Edition", Addison Wesley, 2000. 

[0009] with the ever-increasing popularity of the Internet, there 
is much interest in leveraging Internet architecture for the 
development of applications, including database applica- 
tions. "Web Services" are self-contained modular applica- 



tions that can be published and invoked over a network, 
such as the Internet. Web Services provide well-defined 
interfaces that describe the services provided. Web Ser- 
vices are designed to allow a loose coupling between 
client and server. That is, server implementations do not 
require clients to use a specific platform or programming 
language. In addition to defining interfaces in a language- 
neutral fashion, they are designed to allow multiple com- 
munications mechanisms as well. "Web services" as re- 
ferred herein means any services capable of being served 
up over a Web connection (e.g., HTTP connection). This 
would include, for example, using SOAP (simple object ac- 
cess protocol) services as an RPC (remote procedure call) 
mechanism to make generic calls into a database and 
have the results returned to a Web client. However, Web 
services may also include arbitrary services that can be 
serviced (e.g., in a Web server-like fashion) over the Inter- 
net. 

[0010] Currently, the only way to use Web services in conjunction 
with a database is through some sort of external library. 
Therefore, a database administrator is required to set up 
his or her own combination of a database, a Web server, 
and an external library providing Web services, including 



writing custom code to get all of the components to work 
together properly. In other words, since there is no inte- 
grated solution, today one is required to set up a variety 
of disparate components — none of which are internal to 
the database — to create one's own solution. With that 
approach, there is no effort to leverage the use of 
databases as a means to help facilitate the processing of 
Web services. At best, the current approach provides one 
with a tedious and time-consuming task. 
[0011] what is needed is a solution that provides an easy-to-use 
approach to implementing Web services in conjunction 
with a database. Further, it is desirable that the solution 
be one that is capable of being deployed in embedded en- 
vironments (e.g., providing Web services on handheld de- 
vices). The present invention fulfills this and other needs. 
Summary of Invention 

[0012] a database system providing stored procedures as web 

services is described. In one embodiment, for example, in 
a database system, a method of the present invention is 
described for providing a stored procedure as a Web ser- 
vice, the method comprises steps of: predefining a stored 
procedure to be invoked upon receiving a client request 
for a particular Web service; receiving an incoming request 



from a particular client for the particular Web service; in 
response to the incoming request, identifying the stored 
procedure that is predefined for the particular Web ser- 
vice; executing the identified stored procedure for gener- 
ating a result set; and returning the result set back to the 
particular client. 
[0013] | n another embodiment, for example, a database system 
providing stored procedures as Web services, the system 
of the present invention is described that comprises: a 
database engine controlling a database that includes a 
stored procedure to be invoked upon receiving a request 
for a particular Web service; a communications layer for 
receiving an incoming request from a particular client for 
the particular Web service; an HTTP server for parsing and 
validating the incoming request; a request layer for iden- 
tifying and executing the stored procedure for the partic- 
ular Web service, for generating a result set; and a pre- 
sentation layer for returning the result set back to the 
particular client. 
Brief Description of Drawings 

[0014] pig. 1 is a very general block diagram of a computer sys- 
tem (e.g., an IBM-compatible system) in which software- 
implemented processes of the present invention may be 



embodied. 

[0015] pig. 2 is a block diagram of a software system for control- 
ling the operation of the computer system. 

[0016] pig. 3 illustrates the general structure of a client/server 
database system suitable for implementing the present 
invention. 

[0017] Fig. 4 is a high-level block diagram illustrating an online 
database environment of the present invention for provid- 
ing stored procedures as Web services. 

[0018] Figs. 5A-B comprise a single flowchart illustrating the 

methodology of the present invention for providing stored 
procedures as Web services. 

[0019] Figs. 6A-B comprise a single flowchart illustrating in fur- 
ther detail the steps taken for service determination in re- 
sponse to a request received at the database server. 
Detailed Description 

Glossary 

[0020] The following definitions are offered for purposes of illus- 
tration, not limitation, in order to assist with understand- 
ing the discussion that follows. 

[00 21 ] DISH: DISH stands for Deduce Ideal SOAP Handler. DISH 

services act as a proxy for a number of SOAP services. The 



DISH service also generates a WSDL file for each of the 
SOAP services for which it acts as a proxy. 

[0022] HTML: HTML stands for HyperText Markup Language, the 
authoring language used to create documents on the 
World Wide Web. HTML defines the structure and layout of 
a Web document by using a variety of tags and attributes. 
For further description of HTML, see e.g., "HTML 4.01 
Specification", a World Wide Web consortium recommen- 
dation dated December 24, 1999, the disclosure of which 
is hereby incorporated by reference. A copy of this speci- 
fication is available via the Internet (e.g., currently at 
www.w3.org/TR/REC-html40). 

[0023] HTTP: HTTP is the acronym for HyperText Transfer Proto- 
col, which is the underlying communication protocol used 
by the World Wide Web on the Internet. HTTP defines how 
messages are formatted and transmitted, and what ac- 
tions Web servers and browsers should take in response 
to various commands. For example, when a user enters a 
URL in his or her browser, this actually sends an HTTP 
command to the Web server directing it to fetch and 
transmit the requested Web page. Further description of 
HTTP is available in "RFC 2616: Hypertext Transfer Proto- 
col — HTTP/1.1," the disclosure of which is hereby incor- 



porated by reference. RFC 2616 is available from the 
World Wide Web Consortium (W3C), and is available via 
the Internet (e.g., currently at www.w3.org/Protocols/). 
Additional description of HTTP is available in the technical 
and trade literature, see e.g., Stallings, W., "The Backbone 
of the Web," BYTE, October 1996, the disclosure of which 
is hereby incorporated by reference. 

[0024] Network: A network is a group of two or more systems 
linked together. There are many types of computer net- 
works, including local area networks (LANs), virtual private 
networks (VPNs), metropolitan area networks (MANs), 
campus area networks (CANs), and wide area networks 
(WANs) including the Internet. As used herein, the term 
"network" refers broadly to any group of two or more 
computer systems or devices that are linked together 
from time to time (or permanently). 

[0025] Relational database: A relational database is a collection 
of data items organized as a set of formally-described ta- 
bles from which data can be accessed or reassembled in 
many different ways without having to reorganize the 
database tables. The relational database was invented by 
E. F. Codd at IBM in 1970. A relational database employs a 
set of tables containing data fitted into predefined cate- 



gories. Each table (which is sometimes called a relation) 
contains one or more data categories in columns. The 
standard user and application program interface to a rela- 
tional database is the structured query language (SQL), 
defined below. 

[0026] SOAP: SOAP stands for Simple Object Access Protocol, 

which is a standard and lightweight protocol for exchang- 
ing information in a decentralized, distributed environ- 
ment. It uses XML to encode remote procedure calls, and 
typically uses HTTP as a communications protocol. For 
more information about SOAP, see e.g., "SOAP Version 1.2 
Part 1: Messaging Framework" and "SOAP Version 1.2 Part 
2: Adjuncts," both World Wide Web Consortium (W3C) 
candidate recommendations dated December 19, 2002, 
the disclosure of which are hereby incorporated by refer- 
ence. Copies of these documents are available from the 
W3C, and are available via the Internet (e.g., currently at 
www.w3.org/2002/ws). 

[0027] SQL: SQL stands for Structured Query Language. The orig- 
inal version called SEQUEL (structured English query lan- 
guage) was designed by IBM in the 1970's. SQL-92 (or 
SQL/92) is the formal standard for SQL as set out in a 
document published by the American National Standards 



Institute in 1992; see e.g., "Information Technology - 
Database languages - SQL", published by the American 
National Standards Institute as American National Stan- 
dard ANSI/ISO/IEC 9075: 1992, the disclosure of which is 
hereby incorporated by reference. SQL-92 was super- 
seded by SQL-99 (or SQL3) in 1999; see e.g., "Information 
Technology - Database Languages - SQL, Parts 1-5" pub- 
lished by the American National Standards Institute as 
American National Standard INCITS/ISO/IEC 
9075-(l-5)-1999 (formerly ANSI/ISO/IEC 
9075-(l-5)-1999), the disclosure of which is hereby in- 
corporated by reference. 
[0028] TCP/IP: TCP/IP stands for Transmission Control Protocol/ 
Internet Protocol, the suite of communications protocols 
used to connect hosts on the Internet. TCP/IP uses several 
protocols, the two main ones being TCP and IP. TCP/IP is 
built into the UNIX operating system and is used by the 
Internet, making it the de facto standard for transmitting 
data over networks. For an introduction to TCP/IP, see 
e.g., "RFC 1180: A TCP/IP Tutorial", the disclosure of 
which is hereby incorporated by reference. A copy of RFC 
1180 is available via the Internet (e.g., currently at 
www . i e tf . o rg / rf c / rf c 1 1 8 0 . txt) . 



[0029] URI: Uniform Resource Identifiers (URIs) are short strings 
that identify resources on the Web including documents, 
images, files, services, and other resources. URIs are also 
known as URLs. 

[0030] URL: URL is an abbreviation of Uniform Resource Locator, 
the global address of documents and other resources on 
the World Wide Web. The first part of the address indi- 
cates what protocol to use, and the second part specifies 
the IP address or the domain name where the resource is 
located. 

[0031] WSDL: WSDL stands for Web Services Description Lan- 
guage, which is an XML format for describing network 
services as a set of endpoints operating on messages 
containing either document-oriented or procedure-ori- 
ented information. The operations and messages are de- 
scribed abstractly, and then bound to a concrete network 
protocol and message format to define an endpoint. Re- 
lated concrete endpoints are combined into abstract end- 
points (services). WSDL is extensible to allow description 
of endpoints and their messages regardless of what mes- 
sage formats or network protocols are used to communi- 
cate. For further information on WSDL, see e.g., "Web Ser- 
vices Description Language (WSDL) 1.1", W3C Note, March 



15, 2001, the disclosure of which is hereby incorporated 
by reference. A copy of this document is available via the 
Internet (e.g., currently at www.w3.org/TR/wsdl). 
[0032] XML: XML stands for Extensible Markup Language, a spec- 
ification developed by the World Wide Web Consortium 
(W3C). XML is a pared-down version of the Standard Gen- 
eralized Markup Language (SGML), a system for organiz- 
ing and tagging elements of a document. XML is designed 
especially for Web documents. It allows designers to cre- 
ate their own customized tags, enabling the definition, 
transmission, validation, and interpretation of data be- 
tween applications and between organizations. For further 
description of XML, see e.g., "Extensible Markup Language 
(XML) 1.0", (2nd Edition, October 6, 2000) a recom- 
mended specification from the W3C, the disclosure of 
which is hereby incorporated by reference. A copy of this 
specification is available via the Internet (e.g., currently at 
www.w3.org /TR/REC-xml). 
Introduction 

[0033] Referring to the figures, exemplary embodiments of the 

invention will now be described. The following description 
will focus on the presently preferred embodiment of the 
present invention, which is implemented in desktop and/ 



or server software (e.g., driver, application, or the like) 
operating in an Internet-connected environment running 
under an operating system, such as the Microsoft Win- 
dows operating system. The present invention, however, 
is not limited to any one particular application or any par- 
ticular environment. Instead, those skilled in the art will 
find that the system and methods of the present invention 
may be advantageously embodied on a variety of different 
platforms, including Macintosh, Linux, Solaris, UNIX, 
FreeBSD, and the like. Therefore, the description of the 
exemplary embodiments that follows is for purposes of il- 
lustration and not limitation. The exemplary embodiments 
are primarily described with reference to block diagrams 
or flowcharts. As to the flowcharts, each block within the 
flowcharts represents both a method step and an appara- 
tus element for performing the method step. Depending 
upon the implementation, the corresponding apparatus 
element may be configured in hardware, software, 
firmware or combinations thereof. 
Computer-based implementation 

[0034] Basic system hardware (e.g., for desktop and server computers) 
[0035] The present invention may be implemented on a conven- 



tional or general-purpose computer system, such as an 
IBM-compatible personal computer (PC) or server com- 
puter. Fig. 1 is a very general block diagram of a com- 
puter system (e.g., an IBM-compatible system) in which 
software-implemented processes of the present invention 
may be embodied. As shown, system 100 comprises a 
central processing unit(s) (CPU) or processor(s) 101 cou- 
pled to a random-access memory (RAM) 102, a read-only 
memory (ROM) 103, a keyboard 106, a printer 107, a 
pointing device 108, a display or video adapter 104 con- 
nected to a display device 105, a removable (mass) stor- 
age device 115 (e.g., floppy disk, CD-ROM, CD-R, CD-RW, 
DVD, or the like), a fixed (mass) storage device 116 (e.g., 
hard disk), a communication (COMM) port(s) or inter- 
face(s) 110, a modem 112, and a network interface card 
(NIC) or controller 111 (e.g., Ethernet). Although not 
shown separately, a real time system clock is included 
with the system 100, in a conventional manner. 
[0036] CPU 101 comprises a processor of the Intel Pentium family 
of microprocessors. However, any other suitable proces- 
sor may be utilized for implementing the present inven- 
tion. The CPU 101 communicates with other components 
of the system via a bi-directional system bus (including 



any necessary input/output (1/0) controller circuitry and 
other "glue" logic). The bus, which includes address lines 
for addressing system memory, provides data transfer be- 
tween and among the various components. Description of 
Pentium-class microprocessors and their instruction set, 
bus architecture, and control lines is available from Intel 
Corporation of Santa Clara, CA. Random-access memory 
102 serves as the working memory for the CPU 101. In a 
typical configuration, RAM of sixty-four megabytes or 
more is employed. More or less memory may be used 
without departing from the scope of the present inven- 
tion. The read-only memory (ROM) 103 contains the basic 
input/output system code (BIOS) — a set of low-level rou- 
tines in the ROM that application programs and the oper- 
ating systems can use to interact with the hardware, in- 
cluding reading characters from the keyboard, outputting 
characters to printers, and so forth. 
[0037] M ass storage devices 115, 116 provide persistent storage 
on fixed and removable media, such as magnetic, optical 
or magnetic-optical storage systems, flash memory, or 
any other available mass storage technology. The mass 
storage may be shared on a network, or it may be a dedi- 
cated mass storage. As shown in Fig. 1, fixed storage 116 



stores a body of program and data for directing operation 
of the computer system, including an operating system, 
user application programs, driver and other support files, 
as well as other data files of all sorts. Typically, the fixed 
storage 116 serves as the main hard disk for the system. 
[0038] | n Das j C operation, program logic (including that which 
implements methodology of the present invention de- 
scribed below) is loaded from the removable storage 115 
or fixed storage 116 into the main (RAM) memory 102, for 
execution by the CPU 101. During operation of the pro- 
gram logic, the system 100 accepts user input from a 
keyboard 106 and pointing device 108, as well as speech- 
based input from a voice recognition system (not shown). 
The keyboard 106 permits selection of application pro- 
grams, entry of keyboard-based input or data, and selec- 
tion and manipulation of individual data objects displayed 
on the screen or display device 105. Likewise, the pointing 
device 108, such as a mouse, track ball, pen device, or the 
like, permits selection and manipulation of objects on the 
display device. In this manner, these input devices sup- 
port manual user input for any process running on the 
system. 

[0039] The computer system 100 displays text and/or graphic 



images and other data on the display device 105. The 
video adapter 104, which is interposed between the dis- 
play 105 and the system's bus, drives the display device 
105. The video adapter 104, which includes video memory 
accessible to the CPU 101, provides circuitry that converts 
pixel data stored in the video memory to a raster signal 
suitable for use by a cathode ray tube (CRT) raster or liq- 
uid crystal display (LCD) monitor. A hard copy of the dis- 
played information, or other information within the sys- 
tem 100, may be obtained from the printer 107, or other 
output device. Printer 107 may include, for instance, an 
HP LaserJet printer (available from Hewlett Packard of Palo 
Alto, CA), for creating hard copy images of output of the 
system. 

[0040] The system itself communicates with other devices (e.g., 
other computers) via the network interface card (NIC) 111 
connected to a network (e.g., Ethernet network, Bluetooth 
wireless network, or the like), and/or modem 112 (e.g., 
56K baud, ISDN, DSL, or cable modem), examples of 
which are available from 3Com of Santa Clara, CA. The 
system 100 may also communicate with local occasion- 
ally-connected devices (e.g., serial cable-linked devices) 
via the communication (COMM) interface 110, which may 



include a RS-232 serial port, a Universal Serial Bus (USB) 
interface, or the like. Devices that will be commonly con- 
nected locally to the interface 110 include laptop comput- 
ers, handheld organizers, digital cameras, and the like. 

[0041] IBM-compatible personal computers and server computers 
are available from a variety of vendors. Representative 
vendors include Dell Computers of Round Rock, TX, 
Hewlett-Packard of Palo Alto, CA, and IBM of Armonk, NY. 
Other suitable computers include Apple-compatible com- 
puters (e.g., Macintosh), which are available from Apple 
Computer of Cupertino, CA, and Sun Solaris workstations, 
which are available from Sun Microsystems of Mountain 
View, CA. 

[0042] Basic system software 

[0043] pig. 2 is a block diagram of a software system for control- 
ling the operation of the computer system 100. As shown, 
a computer software system 200 is provided for directing 
the operation of the computer system 100. Software sys- 
tem 200, which is stored in system memory (RAM) 102 
and on fixed storage (e.g., hard disk) 116, includes a ker- 
nel or operating system (OS) 210. The OS 210 manages 
low-level aspects of computer operation, including man- 
aging execution of processes, memory allocation, file in- 



put and output (I/O), and device I/O. One or more appli- 
cation programs, such as client application software or 
"programs" 201 (e.g., 201a, 201b, 201c, 201d) may be 
"loaded" (i.e., transferred from fixed storage 116 into 
memory 102) for execution by the system 100. The appli- 
cations or other software intended for use on the com- 
puter system 100 may also be stored as a set of down- 
loadable processor-executable instructions, for example, 
for downloading and installation from an Internet location 
(e.g., Web server). 
[0044] System 200 includes a graphical user interface (GUI) 215, 
for receiving user commands and data in a graphical (e.g., 
"point-and-click") fashion. These inputs, in turn, may be 
acted upon by the system 100 in accordance with instruc- 
tions from operating system 210, and/or client applica- 
tion module(s) 201. The GUI 215 also serves to display the 
results of operation from the OS 210 and application(s) 
201, whereupon the user may supply additional inputs or 
terminate the session. Typically, the OS 210 operates in 
conjunction with device drivers 220 (e.g., "Winsock" driver 
— Windows' implementation of a TCP/IP stack) and the 
system BIOS microcode 230 (i.e., ROM-based microcode), 
particularly when interfacing with peripheral devices. OS 



210 can be provided by a conventional operating system, 
such as Microsoft Windows 9x, Microsoft Windows NT, Mi- 
crosoft Windows 2000, or Microsoft Windows XP, all avail- 
able from Microsoft Corporation of Redmond, WA. Alter- 
natively, OS 210 can also be an alternative operating sys- 
tem, such as the previously mentioned operating systems. 
[0045] Client-server database management system 

[0046] while the present invention may operate within a single 
(standalone) computer (e.g., system 100 of Fig. 1), the 
present invention is preferably embodied in a multi-user 
computer system, such as a client/server system. Fig. 3 il- 
lustrates the general structure of a client/server database 
system 300 suitable for implementing the present inven- 
tion. As shown, the system 300 comprises one or more 
client(s) 310 connected to a server 330 via a network 320. 
Specifically, the client(s) 310 comprise one or more stan- 
dalone terminals 311 connected to a database server sys- 
tem 340 using a conventional network. In an exemplary 
embodiment, the terminals 311 may themselves comprise 
a plurality of standalone workstations, dumb terminals, or 
the like, or comprise personal computers (PCs) such as the 
above-described system 100. Typically, such units would 
operate under a client operating system, such as a Mi- 



crosoft® Windows client operating system (e.g., Mi- 
crosoft® Windows 95/98, Windows 2000, or Windows XP). 

[0047] The database server system 340, which comprises 
Sybase® Adaptive Server® Anywhere (available from 
Sybase, Inc. of Dublin, CA) in an exemplary embodiment, 
generally operates as an independent process (i.e., inde- 
pendently of the clients), running under a server operating 
system such as Microsoft® Windows NT, Windows 2000, 
or Windows XP (all from Microsoft Corporation of Red- 
mond, WA), UNIX (Novell), Solaris (Sun), or Linux (Red 
Hat). The network 320 may be any one of a number of 
conventional network systems, including a Local Area 
Network (LAN) or Wide Area Network (WAN), as is known 
in the art (e.g., using Ethernet, IBM Token Ring, or the 
like). The network 320 includes functionality for packag- 
ing client calls in the well-known Structured Query Lan- 
guage (SQL) together with any parameter information into 
a format (of one or more packets) suitable for transmis- 
sion to the database server system 340. 

[0048] Client/server environments, database servers, and net- 
works are well documented in the technical, trade, and 
patent literature. For a discussion of Sybase®-branded 
database servers and client/server environments gener- 



ally, see, e.g., Nath, A., "The Guide to SQL Server", Second 
Edition, Addison-Wesley Publishing Company, 1995. For a 
description of Sybase® Adaptive Server® Anywhere Studio, 
see, e.g., "Adaptive Server Anywhere 9.0.1: Core Docu- 
mentation Set," available from Sybase, Inc. of Dublin, CA. 
This product documentation is available via the Internet 
(e.g., currently at sybooks.sybase.com/aw.html). The dis- 
closures of the foregoing are hereby incorporated by ref- 
erence. 

[0049] | n operation, the client(s) 310 store data in, or retrieve 

data from, one or more database tables 350, as shown at 
Fig. 3. Data in a relational database is stored as a series of 
tables, also called relations. Typically resident on the 
server 330, each table itself comprises one or more "rows" 
or "records" (tuples) (e.g., row 355 as shown at Fig. 3). A 
typical database will contain many tables, each of which 
stores information about a particular type of entity. A ta- 
ble in a typical relational database may contain anywhere 
from a few rows to millions of rows. A row is divided into 
fields or columns; each field represents one particular at- 
tribute of the given row. A row corresponding to an em- 
ployee record, for example, may include information 
about the employee's ID Number, Last Name and First Ini- 



tial, Position, Date Hired, Social Security Number, and 
Salary. Each of these categories, in turn, represents a 
database field. In the foregoing employee table, for exam- 
ple, Position is one field, Date Hired is another, and so on. 
With this format, tables are easy for users to understand 
and use. Moreover, the flexibility of tables permits a user 
to define relationships between various items of data, as 
needed. Thus, a typical record includes several categories 
of information about an individual person, place, or thing. 
Each row in a table is uniquely identified by a record ID 
(RID), which can be used as a pointer to a given row. 
[0050] Most relational databases implement a variant of the 

Structured Query Language (SQL), which is a language al- 
lowing users and administrators to create, manipulate, 
and access data stored in the database. The syntax of SQL 
is well documented; see, e.g., the above-mentioned "An 
Introduction to Database Systems". SQL statements may 
be divided into two categories: data manipulation lan- 
guage (DML), used to read and write data; and data defi- 
nition language (DDL), used to describe data and maintain 
the database. DML statements are also called queries. In 
operation, for example, the clients 310 issue one or more 
SQL commands to the server 330. SQL commands may 



specify, for instance, a query for retrieving particular data 
(i.e., data records meeting the query condition) from the 
database table(s) 350. In addition to retrieving the data 
from database server table(s) 350, the clients 310 also 
have the ability to issue commands to insert new rows of 
data records into the table(s), or to update and/or delete 
existing records in the table(s). 
[0051] SQL statements or simply "queries" must be parsed to de- 
termine an access plan (also known as "execution plan" or 
"query plan") to satisfy a given query. In operation, the 
SQL statements received from the client(s) 310 (via net- 
work 320) are processed by the engine 360 of the 
database server system 340. The engine 360 itself com- 
prises a parser 361, a normalizer 363, a compiler 365, an 
execution unit 369, and an access methods 370. Specifi- 
cally, the SQL statements are passed to the parser 361 
which converts the statements into a query tree — a bi- 
nary tree data structure which represents the components 
of the query in a format selected for the convenience of 
the system. In this regard, the parser 361 employs con- 
ventional parsing methodology (e.g., recursive descent 
parsing). 

[0052] The query tree is normalized by the normalizer 363. Nor- 



malization includes, for example, the elimination of re- 
dundant data. Additionally, the normalizer 363 performs 
error checking, such as confirming that table names and 
column names which appear in the query are valid (e.g., 
are available and belong together). Finally, the normalizer 
363 can also look-up any referential integrity constraints 
which exist and add those to the query. 
[0053] After normalization, the query tree is passed to the com- 
piler 365, which includes an optimizer 366 and a code 
generator 367. The optimizer 366 is responsible for opti- 
mizing the query tree. The optimizer 366 performs a 
cost-based analysis for formulating a query execution 
plan. The optimizer will, for instance, select the join order 
of tables (e.g., when working with more than one table), 
and will select relevant indexes (e.g., when indexes are 
available). The optimizer, therefore, performs an analysis 
of the query and selects the best execution plan, which in 
turn results in particular access methods being invoked 
during query execution. It is possible that a given query 
may be answered by tens of thousands of access plans 
with widely varying cost characteristics. Therefore, the 
optimizer must efficiently select an access plan that is 
reasonably close to an optimal plan. The code generator 



367 translates the query execution plan selected by the 
query optimizer 366 into executable form for execution 
by the execution unit 369 using the access methods 370. 
[0054] All data in a typical relational database system is stored in 
pages on a secondary storage device, usually a hard disk. 
Typically, these pages may range in size from 1Kb to 
32Kb, with the most common page sizes being 2Kb and 
4Kb. All input/output operations (I/O) against secondary 
storage are done in page-sized units — that is, the entire 
page is read/written at once. Pages are also allocated for 
one purpose at a time: a database page may be used to 
store table data or used for virtual memory, but it will not 
be used for both. The memory in which pages that have 
been read from disk reside is called the cache or buffer 
pool. 

[0055] |/o to and from the disk tends to be the most costly oper- 
ation in executing a query. This is due to the latency as- 
sociated with the physical media, in comparison with the 
relatively low latency of main memory (e.g., RAM). Query 
performance can thus be increased by reducing the num- 
ber of I/O operations that must be completed. This can be 
done by using data structures and algorithms that maxi- 
mize the use of pages that are known to reside in the 



cache. Alternatively, it can be done by being more selec- 
tive about what pages are loaded into the cache in the 
first place. An additional consideration with respect to I/O 
is whether it is sequential or random. Due to the con- 
struction of hard disks, sequential I/O is much faster then 
random access I/O. Data structures and algorithms en- 
couraging the use of sequential I/O can realize greater 
performance. 

[0056] For enhancing the storage, retrieval, and processing of 
data records, the server 330 maintains one or more 
database indexes 345 on the database tables 350. In- 
dexes 345 can be created on columns or groups of 
columns in a table. Such an index allows the page con- 
taining rows that match a certain condition imposed on 
the index columns to be quickly located on disk, rather 
than requiring the engine to scan all pages in a table to 
find rows that fulfill some property, thus facilitating quick 
access to the data records of interest. Indexes are espe- 
cially useful when satisfying equality and range predicates 
in queries (e.g., a column is greater than or equal to a 
value) and "order by" clauses (e.g., show all results in al- 
phabetical order by a given column). 

[0057] a database index allows the records of a table to be orga- 



nized in many different ways, depending on a particular 
user's needs. An index key value is a data quantity com- 
posed of one or more fields from a record which are used 
to arrange (logically) the database file records by some 
desired order (index expression). Here, the column or 
columns on which an index is created form the key for 
that index. An index may be constructed as a single disk 
file storing index key values together with unique record 
numbers. The record numbers are unique pointers to the 
actual storage location of each record in the database file. 
[0058] indexes are usually implemented as multi-level tree struc- 
tures, typically maintained as a B-Tree data structure. 
Pointers to rows are usually stored in the leaf nodes of the 
tree, so an index scan may entail reading several pages 
before reaching the row. In some cases, a leaf node may 
contain the data record itself. Depending on the data be- 
ing indexed and the nature of the data being stored, a 
given key may or may not be intrinsically unique. A key 
that is not intrinsically unique can be made unique by ap- 
pending a RID. This is done for all non-unique indexes to 
simplify the code for index access. The traversal of an in- 
dex in search of a particular row is called a probe of the 
index. The traversal of an index in search of a group of 



rows fulfilling some condition is called a scan of the in- 
dex. Index scans frequently look for rows fulfilling equal- 
ity or inequality conditions; for example, an index scan 
would be used to find all rows that begin with the letter 
'A'. 

[0059] The above-described computer hardware and software are 
presented for purposes of illustrating the basic underlying 
desktop and server computer components that may be 
employed for implementing the present invention. For 
purposes of discussion, the following description will 
present examples in which it will be assumed that there 
exists a "server" (e.g., database server) that communicates 
with one or more "clients" (e.g., personal computers such 
as the above-described system 100). The present inven- 
tion, however, is not limited to any particular environment 
or device configuration. In particular, a client/server dis- 
tinction is not necessary to the invention, but is used to 
provide a framework for discussion. Instead, the present 
invention may be implemented in any type of system ar- 
chitecture or processing environment capable of support- 
ing the methodologies of the present invention presented 
in detail below. 
Stored procedures as Web services 



[0060] Overview 

[0061] | n accordance with the present invention, a communica- 
tion port (e.g., HTTP) is opened up directly on the 
database engine itself (activated via a command line 
switch). Additionally, a lightweight HTTP server is built di- 
rectly into the database engine. The built-in HTTP server, 
in this configuration, may translate incoming client re- 
quests into stored procedure calls, complete with 
database features (e.g., authentication, mapping, and the 
like). The result set that is returned from a particular 
stored procedure invocation may then be formatted ap- 
propriately as an HTTP response, which may then be re- 
turned back to the client. The system includes a mapping 
table that maps a given client request to a particular 
stored procedure call(s). 

[0062] The database developer authors the individual stored pro- 
cedures that may be invoked in this manner. During sys- 
tem use, when a developer creates a particular Web ser- 
vice of interest, he or she specifies a particular stored 
procedure that is invoked (via a URL) to service client re- 
quests for that web service. Therefore, with the underlying 
functionality provided by the system of the present inven- 
tion, the developer has the flexibility to create any arbi- 



trary number of Web services that he or she may desire. 
System components 

[0063] pig. 4 is a high-level block diagram illustrating an online 
database environment 400 of the present invention for 
providing stored procedures as Web services. As shown, 
the environment 400 includes one or more clients 401 
that interact with a database server 410. The database 
server 410 includes a communications layer 420, an HTTP 
server 431, an HTTP presentation layer 433, an HTTP re- 
quest layer 440, and a database engine 450. The client(s) 
401 represents anything that can issue requests and re- 
ceive a response via HTTP. Examples include a database 
application, a Web browser, run-time library code (e.g., 
portion of Microsoft .NET framework issuing SOAP re- 
quests), a PERL script accessing XML over HTTP, or the 
like. A particular advantage of the present invention is 
that it allows a wide variety of disparate clients to com- 
municate with the system. 

[0064] The communications layer 420 handles incoming requests 
at the database server 410. The communications layer 
420 simply serves to handle communications into and out 
of the database server. Accordingly, the layer also handles 
issues related to obtaining a communication socket (e.g., 



Winsock socket), and handling timeout or error condi- 
tions. This may be implemented using a standard socket- 
based communication library. 

[0065] Requests coming into the communications layer 420 are 
handed off to the HTTP server 431. Note that the HTTP 
server 431 resides in the same executable space as the 
database engine 450. Upon receiving a given request, the 
HTTP server 431 examines the request to make sure that 
it is well formed and valid. For example, in the currently 
preferred embodiment (for servicing HTTP requests), all 
incoming requests must have valid HTTP headers. For in- 
valid requests, the HTTP server 431 returns an error mes- 
sage to the communications layer 420, which in turn re- 
turns an error message to the client 401. If an incoming 
request passes the validity check, the HTTP server 431 
then passes the request to the HTTP request layer 440, 
which performs the bulk of the processing. 

[0066] At the HTTP request layer 440, the request, which is in 

HTTP format, is translated into a form that can be used by 
the database engine 450. The database engine 450 is a 
SQL relational database management system (RDBMS), 
which in the current embodiment is the database engine 
from assignee Sybase's Adaptive Server Anywhere Studio 



version 9 (available from Sybase, Inc. of Dublin, CA). The 
HTTP request layer 440 creates a temporary pseudo con- 
nection to the database engine 450, and the HTTP pre- 
sentation layer 433 is set up to receive the results of the 
stored procedure call. From the perspective of the 
database engine 450, the connection appears to be simply 
an external client connection. Now, the HTTP request layer 
440 can issue the appropriate stored procedure call, mak- 
ing sure that the call executes successfully. 

[0067] importantly, the HTTP presentation layer 433 is set up to 
provide appropriate formatting of the stored procedure 
results, such that those results may be returned to the 
client 401 over the HTTP connection. For example, if the 
system is dealing with a SOAP response, the HTTP presen- 
tation layer 433 (in conjunction with the HTTP request 
layer 440) will format the result set into a SOAP response. 
If the system is simply returning XML, the HTTP presenta- 
tion layer 433 will format the result set into an XML docu- 
ment. Here, the HTTP presentation layer 433 handles 
character set and encoding issues, such as ensuring that 
correct characters are escaped. 

[0068] internally, the HTTP presentation layer 433 includes a 
generic presentation layer that handles issues that are 



common to all HTTP presentation format types. On top of 
this, the HTTP presentation layer 433 includes various 
drivers for the different formats, such as a driver for SOAP 
format, one for XML format, one for WSDL format, and the 
like. The HTTP presentation layer 433 also includes a 
"raw" presentation format which simply provides a pass- 
through format option (i.e., no formatting); this is useful 
when serving up raw HTML pages. The response typically 
includes an HTTP header, but the body itself may be any 
arbitrary format desired (for the task at hand). 
Preferred syntax 

[0069] | n accordance with the present invention, Web service 
statements are embodied using the following syntax: 
[0070] web Service statement syntax: 

[0071] CREATE SERVICE identifier attributes [ AS statement ] 
AL- 
TER SERVICE identifier attributes [ AS { statement | NULL } ] 
DROP SERVICE identifier 
COMMENT ON SERVICE identifier IS comment 

[0072] where, Web Service attributes include: 

[0073] TYPE string 

AUTHORIZATION { ON | OFF } 



SECURE {ON | OFF} 

USER{ user | NULL} 

URL [ PATH ]{ ON | OFF | ELEMENTS } 

USING identifier 

[0074] As shown, these four new statements for controlling Web 
services are SQL-type statements that may be imple- 
mented as SQL extensions. Importantly, in the currently 
preferred embodiment the built-in HTTP server is entirely 
configured and maintained through the use of SQL state- 
ments and a command line switch. In the preferred em- 
bodiment the command line switch -xs is used to control 
how the server handles web services, such as which port 
to listen on for web service requests, and which databases 
should handle the web service requests. However, the Web 
services may be entirely configured and maintained 
through the use of SQL statements. 

[0075] The CREATE SERVICE command is issued to indicate that 
the system should create a new Web service with a partic- 
ular "identifier" (i.e., name) that calls a particular stored 
procedure. The stored procedure itself need not be prede- 
fined at this point, as the system may look up the target 
stored procedure dynamically at runtime. The remaining 
statements, ALTER SERVICE, DROP SERVICE, and COM- 



MENT ON SERVICE, operate in a familiar, self-explanatory 
SQL fashion (e.g., similar to ALTER TABLE, DROP TABLE). 
[0076] The TYPE attribute describes the type of service. In the 
currently preferred embodiment, the following types are 
supported: 

[0077] XML query service; the result set is returned as XML. 
[0078] HTML query service; the result set is returned as HTML. 
[0079] raw query service; the result set is returned as-is. 

[0080] SOAP query service; the request is sent as a SOAP request 
and the result set is returned as a SOAP response. 

[0081] DISH proxy service; DISH services act as proxies for SOAP 
services. DISH services also generate WSDL for SOAP ser- 
vices. 

[0082] T he AUTHORIZATION attribute specifies a level of autho- 
rization (e.g., analogous to SQL roles). More particularly, 
this indicates whether the client must authenticate with 
the engine (e.g., using HTTP authentication) in order to 
access the service. SECURE specifies whether a secure 
communications channel is required. If SECURE is ON, 
then the Web service can only be accessed over a secure 
socket layer (SSL) connection. USER ties in with AUTHO- 
RIZATION. If AUTHORIZATION is OFF, then USER specifies 



which database user the stored procedure is run under. If 
AUTHORIZATION is ON, then USER specifies which 
group(s) of users in the database are authorized to exe- 
cute the Web service. 

[0083] The URL attribute specifies how the URL itself is handled 
by the Web service. In the currently preferred embodi- 
ment, the system allows parameters to be passed as part 
of the URL. Additionally, "URL ELEMENTS" and "URL ON" 
indicate that part of the URL may contain parameters to 
the target stored procedure. This helps with the determi- 
nation of how an incoming request is handled. Consider 
the following sample statements: 

[0084] CREATE SERVICE "a" ... URL ELEMENTS 
CREATE SERVICE "a/b" ... URL ON 
CREATE SERVICE "a/c" ... URL OFF 

[0085] Given those statements, the following URLs are handled as 
shown: 

[0086] http://localhost/a/d/e 
[0087] - handled by "a" 
[0088] _ urll = "d", url2 = "e" 
[0089] http://localhost/a/b/c/d 
[0090] - handled by "a/b" 



[0091] _ url = "c/d" 

[0092] http://localhost/a/c/c 

[0093] _ handled by "a" (not "a/c" since URL is OFF) 

[0094] _ urll = "c", url2 = "c" 

[0095] The USING attribute is used in conjunction with a DISH 

service. When one creates a number of SOAP procedures, 
they may be described by a DISH service, which generates 
the corresponding WSDL. USING allows one to group a 
number of SOAP procedures under one DISH service (i.e., 
provide namespace-type functionality). 

[0096] uRIs used to access HTTP or HTTPS services are commonly 
called URLs. The URLs follow the patterns familiar to any- 
one regularly browsing the Web. As a result, users brows- 
ing through a database server need not be aware that 
their requests are not being handled by a traditional 
stand-alone Web server. Although they do not look un- 
usual, URLs are necessarily interpreted a bit differently 
when sent to a database server. In addition, they are in- 
terpreted differently depending on which options are 
specified when the Web services are created in the 
database server. The general syntax of the URL is as fol- 
lows: 



[0097] <scheme>://<host>[:<port>]/[<dbn>/][<service>][?<pa 

rams>] 

[0098] where, 

[0099] scheme: http or https 

[0100] host: hostname or IP address of the server 

[0101] p 0r t; port number the server is listening on 

[0102] don; database that contains the service 

[0103] service: name of the service 

[0104] params: list of service parameters 

[0105] when the server receives a request, this syntax helps to 
determine which service is in fact going to be accessed. 
Like all standard HTTP requests, the start of the URL con- 
tains the host name or IP number and, optionally, a port 
number. The IP address or host name, and port specified 
should be the one on which the database server is listen- 
ing. 

[0106] The next token (dbn), between the slashes, is the name of 
a database containing the service. After the database 
name, the next portion of the URL is the service name. 
This service must exist in the specified database. The ser- 
vice name may extend beyond the next slash character 



because Web service names can contain slash characters. 
The system matches the remainder of the URL with the 
defined services. If the URL provides no service name, the 
database server looks for a service named "root." If the 
named service, or the root service, is not defined, the 
server returns a "404 Not Found" error. However, root 
services may be defined to serve a role analogous to the 
role of index.html pages in many traditional Web servers. 
Root services are useful for creating home pages because 
they can handle URL requests that contain only the ad- 
dress of a Web site. 

[0107] Depending on the type of the target service, parameters 
can be supplied in different ways. Parameters to HTML, 
XML, and RAW services can be passed in any of the fol- 
lowing ways: 

[° 108 ] appended to the URL 

[° 109 ] supplied as an explicit parameters list 

supplied as POST data in a POST request 

[0111] Parameters to SOAP and DISH services should be included 
as part of a standard SOAP request as values supplied in 
other ways are generally ignored. To access parameter 
values, parameters should be given names. These host 



variable names, prefixed with a colon (:), may be included 
in the statement that forms part of the Web service defini- 
tion. For example, a statement that calls the procedure 
"place.order" may require product identification number 
and size parameters as follows: 
[° 112 ] call place_order( :product, :quantity ) 

[0113] Variables in HTTP requests come from one of two sources. 
First, the URL may include a query, which is a list of 
"name=value" pairs separated by the "&" character. This 
list is introduced by a question mark. GET requests are 
formatted in this manner. If present, the named variables 
are defined and assigned the corresponding values. 

[0114] The second source is through the URL path. Setting the 

URL PATH to either ON or ELEMENTS causes the portion of 
the path following the service name to be interpreted as 
variable values. This option allows URLs to appear to be 
requesting a file in a particular directory, as would be the 
case on a traditional file-based Web site, rather than 
something stored inside a database. For example, the URL 
http://localhost/gallery/sunset.jpg appears to request the 
file sunset.jpg from a directory named gallery, but instead 
asks the gallery service to retrieve a picture from a 
database table. The parameter passed in HTTP requests 



depends on the setting of the URL PATH: 
[0115] OFF: No path parameters are permitted after the service 
name. 

[0116] ON: All path elements after the service name are assigned 
to the variable URL. 

[O 117 ] ELEMENTS: The remainder of the URL path is split at the 
slash characters into a list of up to 10 elements. These 
values are assigned the variables URL1, URL2, URL3, 
URL10. If there are fewer than 10 values, the remaining 
variables are set to NULL. Specifying more than ten vari- 
ables causes an error. 

[0118] Apart from the location in which they are defined, there is 
no difference between variables. HTTP variables can all be 
accessed and used the same way. For example, the values 
of variables such as URL1 are accessed in the same way as 
parameters that appear as part of a query, such as 
"?picture=sunset.jpg". 
Detailed operation 

[0119] Methodology 

[0120] The following description presents method steps that may 
be implemented using processor-executable instructions, 
for directing operation of a device under processor con- 



trol. The processor-executable instructions may be stored 
on a computer-readable medium, such as CD, DVD, flash 
memory, or the like. The processor-executable instruc- 
tions may also be stored as a set of downloadable proces- 
sor-executable instructions, for example, for downloading 
and installation from an Internet location (e.g., Web 
server). 

[0121] pigs. 5A-B comprise a single flowchart 500 illustrating the 
methodology of the present invention for providing stored 
procedures as Web services. At the outset, an incoming 
HTTP request is received from a client, as indicated at 
step 501. The communication layer in the database sys- 
tem receives this incoming request (on the socket layer 
that is listening for HTTP requests), at step 502. During 
the step, the communication layer will maintain the in- 
tegrity of the communication socket (e.g., handling error 
conditions and the like). Internally, this functionality is 
manifested through an HTTP Listener object that sits on 
the socket waiting for incoming HTTP requests. When a 
request comes in, the HTTP Listener object creates or in- 
vokes an HTTP Connection object, which maintains a cor- 
responding HTTP connection. Information passed back 
and forth between the client and the database engine 



flows over this HTTP connection. 

[0122] The incoming request is passed to the built-in HTTP 

server, as indicated at step 503. At this point, the HTTP 
server parses the request to ensure that it is well formed. 
Additionally, the HTTP server waits to receive the entire 
request before presenting it to the database engine. The 
HTTP server is the portion of the system that understands 
HTTP protocol. Therefore, it is the component that deter- 
mines which Web service is being accessed, and is re- 
sponsible for correctly parsing the information contained 
within the HTTP header and HTTP body (of the HTTP re- 
quest). More particularly, the HTTP server creates an HTTP 
Request object, as indicated at step 504. This object in- 
cludes member fields that store information indicating 
which Web service is being accessed and what are the 
particular parameters being passed. 

[0123] The HTTP Request object is now ready to be passed to the 
HTTP request layer, as shown at step 505. The request 
layer takes the HTTP Request object and creates a tempo- 
rary or pseudo connection directly into the database en- 
gine itself, at step 506. As previously-mentioned, the 
pseudo connection appears as an outside client to the 
database engine. The request layer uses the provided au- 



thentication information (if any) to authenticate the client 
to the database engine, as indicated at step 507. Now, at 
step 508, the request layer may create a cursor to execute 
the target stored procedure (associated with the identified 
Web service); at this point, the request layer will fill in any 
necessary parameters for the stored procedure, using the 
parameter information currently stored in the HTTP Re- 
quest object. Next, the request layer will execute the cor- 
responding (target) stored procedure specified for the re- 
quested Web service, as shown at step 509. This stored 
procedure may include any valid SQL statement (e.g., in- 
cluding SELECT, INSERT, UPDATE, and the like), and may 
invoke other available stored procedures (e.g., nested 
calls to one or more other stored procedures). The execu- 
tion of the stored procedure occurs asynchronously (with 
respect to the incoming client requests); this is achieved 
by queuing up (at the HTTP server) incoming client re- 
quests, which are then processed asynchronously. There- 
fore, multiple requests may come in from a given client 
even though some of that client's prior requests are still 
queued up for processing. As a result of the stored proce- 
dure execution, a result set may be returned from the 
stored procedure, as indicated at step 510. (If no result 



set is specified for return from the stored procedure, the 
method at this point simply returns a null set.) 

[0124] Through the HTTP Requests object, the target stored pro- 
cedure has access to all of the HTTP headers, which may 
include additional parameters or variables. Parameters are 
initially supplied as: 

[0 12 5] part of the URL (URL { ON | ELEMENTS }) 

part of the explicit parameter list (e.g, http://localhost/se 
rvice?x=y) 

part of the POST data 
part of the SOAP request 
[0126] Parameters are declared by specifying host variables: 

[0127] CREATE SERVICE ... AS CALL foo( :bar ) 

[0128] The value of the parameter "bar" is passed as the first pa- 
rameter to the procedure "foo". 

[0129] | n the currently preferred embodiment, this access to pa- 
rameter information in the HTTP Request object is pro- 
vided by internal SQL stored procedures and built-in 
functions: 

[0130] http_header( name ): built-in function that gets the value 

of an http request header 
[° 131 ] next_http_header( name ): built-in function that gets the 



next http request header name; useful for iterating over 

request headers 
[0132] dbo.sa_set_http_header( name, value ): internal stored 

procedure (defined when one's database is initialized) that 

sets the value of an http response header 
[0133] dbo.sa_set_http_option( name, value ): internal stored 

procedure (defined when one's database is initialized) that 

sets the value of an http option 
[0134] http_variable( name [, i ]): built-in function that gets the 

ith value of the named host variable 
[0135] next_http_variable( name ): built-in function that gets the 

next http host variable name; useful for iterating over 

host variables 

[0136] when returning from execution, a Web service stored pro- 
cedure may also return (in addition to a result set) addi- 
tional information for placement in the HTTP headers (for 
return to the client). Therefore, this mechanism may be 
used to pass other information from a given stored proce- 
dure back to the client, including returning output vari- 
ables (parameters), cookies, or the like. In the currently 
preferred embodiment, the setting of output information 
(in HTTP headers) is done by calling into an internal 
(system) stored procedure "dbo.sa_set_http_header " 



(from the developer's Web service stored procedure). 
[0137] At s t e p 5n j the information is returned back to the re- 
quest layer, which has preserved the pseudo connection. 
In the currently preferred embodiment, the information is 
streamed back to the request layer as it becomes avail- 
able. Upon receiving this information, the request layer 
proceeds to forward it on to the presentation layer, at step 
512. Now, the presentation layer may format the informa- 
tion for a specific output (e.g., raw, XML, WSDL, etc.), as 
indicated at step 513. Internally, the returning data gets 
routed to the appropriate format class, which manipulates 
the presentation of the data in a way appropriate for the 
target format (e.g., XML document for XML format, SOAP 
envelope for SOAP format, etc.). Now, the system has a 
properly formatted data object that is ready to be re- 
turned to the client. Accordingly, at step 514, the format- 
ted data is returned to the communication layer, which 
maintains socket connections with various clients. Finally, 
at step 515, the formatted data object is returned over the 
communication socket back to the client, thus completing 
the HTTP response. The HTTP response itself is stateless, 
meaning that it is independent of other HTTP responses 
that may be returned over the communication socket to 



the client. 

[0 1 38] Service determination 

[0139] pigs. 6A-B comprise a single flowchart 600 illustrating in 
further detail the steps taken for service determination in 
response to a request received at the database server. At 
step 601, a check is made to determine whether the con- 
nection is from an acceptable host when a request is re- 
ceived. If so, the entire request from the client is read at 
step 602. As the request is read it is checked to verify that 
it is a valid HTTP or HTTPS request. At step 603, the HTTP 
header is parsed to extract the method, URI, and version 
information. In the currently preferred embodiment, a 
check is also made to verify that the HTTP method is one 
of GET, HEAD, or POST at step 604. This is necessary as 
these are the only methods currently supported in the 
currently preferred embodiment of the system. When this 
is complete, the request is queued to be processed at step 
605. 

[0140] when the queued request is picked up by an engine 

worker several additional steps are performed. At step 
606, a determination is made as to which database is to 
service this request. If the port -xs DBN parameter speci- 
fied a database name, then the database having this name 



is used. If the DBN parameter is required, the first element 
is extracted from the URI and used as the database name. 
Otherwise, the first URI element is extracted from the re- 
quest and a determination is made as to whether it is the 
name of a loaded database. If the name is not determined 
by the above steps, then the name of the server's default 
database is used. If the named database is not loaded, 
then a "404 Not Found" error is returned. 

[0141] After the database has been determined, the service to be 
executed is determined by looking up the service infor- 
mation in a "SYSWEBSERVICE" table at step 607. If no ser- 
vice name has been specified in the URI, then a default 
"root" is used. If the named service does not exist, a "404 
Not Found" error is returned. Next, a check is made to de- 
termine if the service requires a secure connection. If the 
service requires a secure connection and the connected 
port is not HTTPS, then at step 608 it is redirected to the 
HTTPS port by issuing a "301 Moved Permanently" re- 
sponse. In the event that no HTTPS port has been started, 
a "403 Forbidden" error is returned. 

[0142] At step 609, the system ensures that the request is ap- 
propriately authenticated if necessary. If authentication is 
required and no authentication information has been 



given, a "401 Unauthorized response" will be given (Note: 
this response will cause most browsers to prompt for the 
user id and password). A 401 error is also returned if an 
invalid user id or password is given. 
[0143] if the above steps are successfully completed, the request 
is processed at step 610. At this step if the service type is 
DISH and the URI parameter field contains "wsdl", then the 
WSDL description of the associated SOAP services is gen- 
erated. Otherwise, the "SOAPAction" HTTP header speci- 
fies the SOAP service to be executed and the request is 
handled as a SOAP request (as described below). For all of 
the other service types (e.g., SOAP, XML, HTML, and RAW) 
the statement that is to be executed is determined and 
executed. The statement to be executed is generally de- 
fined by the service or, if it is null, the URI parameters 
field. At step 611, the output of the request is formatted 
according to the service type. The output is formatted as 
follows: 

[0144] XML: if the result set is not formatted (by the query) as 
XML, then the result set is formatted as if FOR XML RAW 
was added to the query. 

[° 14 5] HTML: the result set is formatted as an HTML table. 

[0146] RAW: each column of the result set is described as a 



STRING and concatenated together as one byte stream. 
[0147] SOAP: the result set is formatted as an SOAP XML re- 
sponse. 

[0148] wSDL: the output is a WSDL XML document. 

[0149] The default is to convert all non-binary output from the 
database character set to the character set requested by 
the client (HTTP header "Accept-Charset"). If charset con- 
version is not wanted, the result column is cast to BINARY 
and/or the result type of the procedure is described as BI- 
NARY. Alternatively, a dbo.sa_set_http_option( 'Charset- 
Conversion', 'OFF' ) can be used. A built-in function 
"csconvertO" can be used to convert a selective set of 
data. 

[01 50] internal stored procedures /built-in functions 

[0151] The following describes some built-in functions (internal 
stored procedures) provided in the currently preferred 
embodiment of the system in further detail. 

[0152] http_header( fieldname ): This built-in function can be 
used to obtain a value for an HTTP header. 

[0153] dbo.sa_set_http_header( fieldname, value ): This is an in- 
ternal stored procedure that allows the Web service to set 
an HTTP header in the result. The special header named 



"@HttpStatus" may be set to supply the HTTP status code 
that is to be returned by the request. For example, if the 
service wants to indicate a "404 Not Found" return code, it 
can use dba.sa_set_http_header( '@HttpStatus\ '404' ). If 
the given status code is invalid, a SQL error is issued. It is 
up to the stored procedure to fill in the body of the re- 
sponse appropriately for the given status code. 

[0154] dbo.sa_set_http_option( optionname, value ). This is an 
internal stored procedure that allows the Web service to 
set an HTTP option. Currently only one option is defined: 
"CharsetConversion" - either "ON" or "OFF" (default "ON") 
- specifies whether the output is to be converted from the 
database character set to the client character set. 

[0155] http_variable( varname [, i] ): This built-in function returns 
the value of the i'th host variable value associated with the 
given name. If "i" is omitted, it defaults to 1. This routine 
can be useful when a multiple select list is used in an 
HTML form and the request has specified more than one 
value. There are three special variables that allow access 
to the HTTP request information: "@HttpMethod" - the 
HTTP method being used (GET, POST, or HEAD); 
"@HttpURI" - the full HTTP URI of the request; and 
"@HttpVersion" - the HTTP version string specified in the 



request. 

[0156] next_http_header( name ): This built-in function iterates 
over the list of HTTP headers that are defined in the HTTP 
request. If name is NULL then the name of the first header 
is returned. If name is not NULL then the next name is re- 
turned. If the return value is NULL then the end of the list 
is reached. 

[0157] next_http_variable( name ): This built-in function iterates 
over the list of host variables that are defined in the HTTP 
request. If name is NULL then the first variable name is 
returned. If name is not NULL then the next name is re- 
turned. If the return value is NULL then the end of the list 
is reached. 
Program code embodiment 

[0 1 58] i m HTTP connection 

[0159] | n the currently preferred embodiment, an "HttpConnec- 
tion" class may be declared as follows (with line numbers 
being added for convenience of discussion). 

[0160] 32: class HttpConnection { 
33: public: 

34: HttpConnection * _next; 
35: protected: 



36: HttpSocket * .socket; 

37: HttpSockOStream * .stream; 

38: HttpConnectionState .state; 

39: HttpProtocol * .protocol; 

40: HttpRequest * .request; 

41: HttpListener * .listener; 

42: HttpString .rmt.addr; 

43: HttpString JcLaddr; 

44: HttpString .rxline; 

45: char* .dbname; 

46: HttpString .dbConnected; 

47: char * .rxbuffer; 

48: char * .decrypt.buffer; 

49: char .last; 

50: HttpRxCompletion * .rxcomplete; 

51: HttpTxCompletion * .txcomplete; 

52: uint32 .request.size; 

53: uint32 .pkts.received; 

54: a_fast_tod .last.read.time; 

55: a_bool .ignore.receive; 

56: a_bool .dbname.required; 

57: a_bool .dbname.provided; 

58: a_web_protocol_type .type; 



59: public: 

60: HttpConnection( SysSocket sock, char *dbn, a_web_ 

protocoLtype 

type, 



61 
62 
63 
64 
65 
66 
67 
68 
69 



HttpListener *l, char *lcl_addr, char *rmt_addr ); 
~HttpConnection(); 
void Start( void ); 

void Stop( a_bool on.worker = FALSE ); 

void DelayedStop( void ); 

void RequestFinished( void ); 

void CleanUp( void ); 

void ProcessSend( int err, int datalen ); 

a_bool ProcessLine( char * rxbuffer, int * offset, in 



t datalen 

); 

70: void ProcessRecv( int err, int datalen ); 

71: void ProcessData( char *, int ); 

72: void ProcessHttpsRecv( a_bool force = FALSE ); 

73: void IgnoreReceiveQ; 

74: a_web_protocol_type GetType( void ) const { return 
-type; } 

75: char* GetDbName( void ) const { return _dbname; 
} 



76: a_bool DBNameRequired( void ) const { return _db 

name.required; 

} 

77: a_bool DBNameProvided( void ) const { return _db 

name.provided; 

} 

78: char * GetDbConnected( void ) const { return 

_dbConnected.c_str(); } 

79: void SetDbConnected( char *str ) { 

80: _dbConnected.clear(); 

81: _dbConnected.append( str ); 

82: } 

83: HttpListener * CetListener( void ) const { return _lis 
tener; } 

84: HttpProtocol * GetProtocol( void ) const { return _pr 
otocol; } 

85: HttpRequest * CetRequest( void ) const { return _re 
quest; } 

86: HttpOrderedList * GetVariables( void ) const { retur 
n 

_request->GetVariables(); } 

87: a_bool ParseRequestString( HttpRequest *request, 
HttpString 



*str ); 

88: a_bool ParseHeaderString( HttpRequest *request, 
HttpString 

*str ); 



89 


a_bool 


ParseURK HttpRequest * request ); 


90 


a_bool 


ParseVersion( HttpRequest * request ); 


91 


a_bool 


CanDelete( void ); 


92 


a_bool 


CheckForTimeout( void ); 


93 


a_bool 


SendHttpHeaders( HttpRequest *request, H 



ttpOStream 
*stream ); 

94: a_bool SendHttpError( HttpRequest *request, Http 

OStream 

*stream ); 

95: a_bool SendSQLError( HttpRequest *request, Http 
OStream *stream 

); 

96: a_bool lsSecure( void ) const; 

97: void UpdateReceivedConnProperties( p.Connectio 

n ) const; 

98: void UpdateSentConnProperties( p.Connection ) c 
onst; 

99: void GetRemoteMachineAddr( char *buf, int32 buf 



len ); 

100: uint32 GetldleTimeout( void ) const; 

101: a_fast_tod Getl_astRequestTime( void ) const { ret 

urn 

_last_read_time; } 

102: HttpString *Getl_ocalMachineAddr( void ) { retur 
n &_lcl_addr; } 

103: int64 GetBytesWritten( void ) const { return 
_socket->getBytesWritten(); } 
104: protected: 

105: HttpSockOStream * GetStream() const { return _ 
stream; } 

106: friend class HttpListener; 
107: friend class HttpProtocol; 
108: private: 

109: void StartRequestO; 
110: }; 

[0161] As shown at line 34, the class includes a linked list (data 
member) to other HTTP connections. At line 36, the class 
includes a data member that is an object of an "Http- 
Socket" class, which is a simple wrapper for the system's 
internal socket mechanism. To communicate with the out- 
side world, the presentation layer uses an output stream, 



"HttpSockOStream", declared at line 37. The connection 
state itself is tracked by state variable "HttpConnection- 
State", at line 38. "HttpListener" (line 41) represents a 
pointer to a listener object, which resides in the commu- 
nication layer and listens for incoming requests. Whenever 
a new connection comes in, the listener creates a new 
connection object. Addresses for the connection are 
stored as strings (at lines and 42-43). Other housekeep- 
ing information is maintained by data members through 
line 58, as shown; these maintain connection state infor- 
mation. Also shown in the class definition are various 
class methods (prototypes) at lines 59-110. These imple- 
ment conventional processing steps for maintaining con- 
nections and the aforementioned state information. 

[0162] of interest are the following two class methods, "SetHTTP- 
HeaderField" and "SetHTTPOption". 

[0163] 1291: a _bool Connection::SetHTTPHeaderField( char * fldn 
ame, char * val ) 

1292" i*************************************************** 
************** I 

1293: { 

1294: a_bool result = FALSE; 

1295: if( http.conn != NULL && fldname != NULL && *fl 



dname != '\0' ) { 

1296: result = http_conn->GetProtocol()->SetResponse 
Header( fldname, val 
= = NULL?"" : val ); 
1297: } 

1298: return( result ); 

1299: } 

1300: 

1301: 

1302: 

1303: 

1304: a_bool Connection::SetHTTPOption( char * optname 
, char * val ) 

******* i 
1306: { 

1307: a_bool result = FALSE; 

1308: if( http.conn != NULL && optname != NULL && *o 
ptname != '\0' ) { 

1309: result = http_conn->CetProtocoK)->SetHTTPOpti 
on( optname, 

1310: (char *)( val == NULL?"" : val ) ); 
1311: } 



1312: return( result ); 
1313: } 

[0164] "SetHTTPHeaderField" and "SetHTTPOption" are internal 
functions that allow one's stored procedure to set HTTP 
header information. For example, when one calls the sys- 
tem-level stored procedure ("sa_set_http_option") in one's 
own stored procedure, the call (see, e.g., line 1273 in pro- 
gram code appendix) is routed to "SetHTTPOption" (see, 
e.g., line 1280 in program code appendix). As shown, the 
"SetHTTPHeaderField" and "SetHTTPOption" methods 
themselves are stub functions that call through to the ac- 
tual respective setter/getter methods in the "HttpConnec- 
tion" class (which in turn update the respective hash ta- 
bles). 

[0165] The "SetResponseHeader" method is used in a corre- 
sponding manner to set HTTP response header informa- 
tion; it may be implemented as follows. 

[0166] 1336: a _bool HttpProtocol::SetResponseHeader( const cha 
r * key, const char 
* value ) 

1337" i*************************************************** 
*************** I 

1338: { 



1339: _assertD( key != NULL ); 

1340: if(*key == '@' ) { 

1341: // special values 

1342: if( _strieq( key, "@HttpStatus" ) ) { 

1343: // value had better be the numeric status code 

1344: int v = atoi( value ); 

1345: int i = StatusLinelndex( v ); 

1346: if(i == LEVEL.600 ) { 

1347: // invalid value 

1348: return FALSE; 

1349: } 

1350: SetHttpStatus( (HttpStatus)v ); 
1351: return TRUE; 
1352: } 
1353: } 

1354: // check that the key and value consists of valid 
HTTP characters 
1355: const char * s; 

1356: #define IS_HTTP_TOKEN_CHAR( c ) ( (c)>* ' && (c)< = 
&& 

!lsHttpSeparator( c ) ) 

1357: #define VALID_HTTP_KEY_CHAR( c ) IS_HTTP_TOKEN 
_CHAR( c ) 



1358: #define VALID_HTTP_VAL_CHAR( c ) ( ((c)>=' ' && (c) 

<='-') II 

(c)==V) 

1359: // TBD: we need to handle LWS (continuation line 

s) in the field 

values 

1360: for( s=key; *s != '\0'; s++ ) { 
1361: if( !VALID_HTTP_KEY_CHAR( *s ) ) { 
1362: return FALSE; 
1363: } 
1364: } 

1365: for( s=value; *s != '\0'; s++ ) { 
1366: if( !VALID_HTTP_VAL_CHAR( *s ) ) { 
1367: return FALSE; 
1368: } 
1369: } 

1370: .response. Set( key, value ); 
1371: return TRUE; 
1372: } 

[0167] of interest, the program logic to set the HTTP status 
(beginning at line 1342) is where the system deduces 
whether it can return a special HTTP code (e.g., HTTP code 
401). The remainder of the method ensures that the HTTP 



"key" part of the header is valid, and will raise an SQL er- 
ror if it is not. 

[0 1 68] 2. HTTP presentation 



[0169] | n the currently preferred embodiment, an "HttpPres" 
(presentation) class may be declared as follows: 



[0170] H5 


rla^ HttnPrps ■ nuhlir ^tuhPrp^ I 


116 


nrotprtpH ■ 


117 


HttoOStrpam * ostrpanv 


118 


UTCollation * _col; // db's collation 


119 


HttpPresStatus .status; 


120 


HttpOrderedList * _args; 


121 


uint32 _arg_id; 


122 


uint32 _arg_len; 


123 


a_byte * _arg_data; 


124 


uint32 _descriptor_count; // number of column 


s in query 


125 


uint32 _row_ctr; // number of rows written 


126 


uint32 _col_ctr; // number of columns describ 



ed/written 

127: a_ptrint _bin_bits; // which columns are binary 
data 

128: a_bool _printed_doc; // has any doc been writt 



129: a_bool _started_doc; // has the doc been start 
ed 

130: a_bool _started_set; // has started the result s 
et 

131: a_bool _started_row; 

132: a_bool _wants_null_values; // output wants to s 
how nulls 

133: a_bool PutData( char ** buf, size_t len, uint32 flag 

s); 

134: a_bool PutData( char * buf, size_t len, uint32 flags 
) 

135 
136 
137 
138 
V);} 
139 
140 
141 
142 
143 
144 



{ return PutData( &buf, len, flags ); } 
// Put data Encoded & Charset-converted 
inline a_bool PutEC( char * buf ) 
{ return PutData( buf, _strlen(buf), HF_ENC|HF_CON 

inline a_bool PutEC( char ** buf, size_t len ) 
{ return PutData( buf, len, HF_ENC|HF_CONV ); } 

inline a_bool PutEC( char * buf, size_t len ) 
{ return PutData( buf, len, HF_ENC|HF_CONV ); } 

inline a_bool PutEC( HttpString & str ) 
{ return PutData( str.strQ, str.length(), HF_ENC|HF_C 



ONV); } 



145: // Put data Charset-converted (no encoding) 

146: inline a_bool PutCC( char ch ) 

147: { return PutData( &ch, 1, HF.CONV ); } 

148: inline a_bool PutCC( char * buf ) 

149: { return PutData( buf, _strlen(buf), HF.CONV ); } 

150: inline a_bool PutCC( char * buf, size_t len ) 

151: { return PutData( buf, len, HF.CONV ); } 

152: inline a_bool PutCC( HttpString & str ) 

153: { return PutData( str.strQ, str.length(), HF.CONV ); } 

154: // Put ASCII data - not encoded, and not Charset- 
converted unless 
it needs 

155: // to be (i.e. output character set is multi-byte) 

156: inline a_bool PutAsc( char c ) 

157: { return PutData( &c, 1, HF.ASC ); } 

158: inline a_bool PutAsc( char * buf) 

159: { return PutData( buf, _strlen(buf), HF_ASC ); } 

160: inline a_bool PutAsc( char * buf, size_t len ) 

161: { return PutData( buf, len, HF.ASC ); } 

162: inline a_bool PutAsc( HttpString & str ) 

163: { return PutData( str.str(), str.length(), HF_ASC ); } 

164: public: 

165: HttpPres( HttpOStream * ostream, UTCollation * co 



I) 

166: : StubPresO 

167: , _ostream( ostream ) 

168: ,_col(col) 

169: , _status( PRES.OK ) 

170: , _args(NULL) 

171: , _arg_id(0) 

172: ,_arg_len(0) 

173: , _arg_data( NULL) 

174: , _descriptor_count( 0 ) 

175: ,_row_ctr(0) 

176: , _col_ctr(0) 

177: , _bin_bits( 0 ) 

178: , _printed_doc( FALSE) 

179: , _started_doc( FALSE ) 

180: , _started_set( FALSE ) 

181: , _started_row( FALSE ) 

182: , _wants_null_values( TRUE ) 

183: { 

184: } 

185: virtual -HttpPresO; 

186: inline HttpPresStatus CetPresStatus( void ) 
187: { 



188: return .status; 
189: } 

190: inline a_bool PresStatusOk( void ) 
191: { 

192: return .status == PRES.OK; 
193: } 

194: void SetArguments( HttpOrderedList * args ) 
195: { 

196: // Note: caller responsible for freeing args. 
197: _args = args; 
198: } 

199: a_bool ReceiveHostVariable( an_sqlpres_value *val 
ue, uint32 
*index ); 

200: a_bool ReceiveMultiBegin( uint32* totaLlength ); 
201: a_bool ReceiveMultiPiece( void * buff, uint32 buff 
Jen, uint32* 
recvjen ); 

202: a_bool ReceiveMultiEnd( void ); 

203: void ReportSQLError( HttpProtocol * proto ); 

204: protected: 

205: a_bool lsBinaryColumn( uint32 c ); 

206: inline void SetPresStatus( HttpPresStatus status ) 



207: { 

208: if( .status == PRES.OK ) { 

209: .status = status; 

210: } 

211: } 

212: void MakeErrorString( char * buff, size.t len, a. 
bool 

replace.quotes ); 

213: public: 

214: // methods inherited from StubPres 

215: a_bool SendValueSetDescriptor( uintl6 desc.id, 

216: char *coln_name, 

217: uintl6 coln.namelen, 

218: char *table_name, 

219: char *db_name, 

220: char *user_name, 

221: a_byte asa_domain_id, 

222: uint32 asa_usertype, 

223: uint32 asa_flags, 

224: uint32 asa_maxlen, 

225: uintl6 asa_prec, 

226: uintl6 asa_scale, 

227: a_describe_flag describe_flags ); 



228: a_bool ReceiveDescriptor( an_sqlpres_desc * desc 

); 

229: a_bool SendValue( a_domain_number domain_id, 
void * data, uint32 

len, uint32 truelen, a_textptr_value * textptr ); 

230: a_bool SendNullValue( a_domain_number domain 

_id, p_expr expr ); 

231: a_bool SendNoneValue( a_domain_number domai 
n_id ); 

232: a_bool SendMultiBegin( a_domain_number domai 

n_id, uint32 

to- 

taljength, uint32 untruncatedjength, a_textptr_value * te 
xtptr, 

uint32 flags ); 

233: a_bool SendMultiPiece( void ** data, uint32 piece, 
length, uint32 
flags ); 

234: a_bool SendMultiEnd( uint32 flags ); 

235: a_bool SendValueSetRow( an_error_mapping *err 

map, 

an_sqlpres_tran_status tran_status ); 

236: a_bool SendSuccessOrError( p_Connection conn, 



237: a_bool sencLiocount, 

238: a_bool send_tran_flags ); 

239: a_bool SendRequestDone( void ); 

240: a_bool SyncPoint( void ); 

241: class DBConn Converter *GetConverter( void ) { 

242: return _ostream->getConverter(); 

243: } 

244: const class Charsetlnfo *GetCharsetlnfo( void ) { 

245: return _ostream->getCharsetlnfo(); 

246: } 

247: protected: 

248: // methods that control output 

249: virtual void AddColumn( 
250: char* table.name, 
251: char* coln.name, 
252: uintl6 coln.namelen, 
253: uint32 asa_usertype ) 

254: { 

255: _unused( table.name ); 

256: _unused( coln.name ); 

257: _unused( coln.namelen ); 

258: _unused( asa_usertype ); 
259: }; 



260: virtual void BeginDoc( void ) {}; // output doc he 
ader 

261: virtual void BeginResultSet( void ) {}; // start of re 
suit set 

262: virtual void BeginRow( void ) {}; 

263: virtual void BeginColumn( void ) {}; 

264: virtual void EndColumn( void ) {}; 

265: virtual void EndRow( void ) {}; 

266: virtual void EndResultSet( void ) {}; 

267: virtual void EndDoc( void ) {}; 

268: virtual void SendColumnValue( void * data, uint32 

len){ 

_unused(data); _unused(len); }; 

269: virtual void SendColumnNull( void ) {}; 

270: virtual void SendColumnNone( void ) {}; 

271: virtual void SendColumnMultiBegin( void ) {}; 

272: virtual void SendColumnMultiPiece( void ** data, ui 

nt32 len){ 

_unused(data); _unused(len); }; 

273: virtual void SendColumnMultiEnd( void ) {}; 

274: virtual void SendSQLError( void * errmsg, size_t le 

n ) = 0; 

275: virtual void NoContentDocBody( void ) {}; // called 



when doc has 
no content 
276: private: 

277: // these routines guarantee that the virtual versio 
ns are called 
in correct order 

278: inline void DoBeginDoc( a_bool starting_a_row ) 
279: { 

280: if( ! _started.doc ) { 
281: BeginDocO; 
282: if( starting_a_row ) { 
283: BeginResultSetO; 
284: _started_set = TRUE; 
285: } 

286: _started.doc = TRUE; 
287: _printed_doc = TRUE; 
288: } 
289: } 

290: inline void DoBeginRow( void ) 
291: { 

292: if( ! _started_row ) { 

293: DoBeginDoc( TRUE ); // ensure we've started th 
e doc 



294: BeginRowO; 

295: _started_row = TRUE; 

296: _col_ctr = 0; 

297: _row_ctr + + ; 

298: } 

299: } 

300: inline void DoBeginColumn( void ) 

301: { 

302: DoBeginRowO; // ensure we have started a row 

303: BeginColumnO; 

304: } 

305: inline void DoEndColumn( void ) 

306: { 

307: EndColumnO; 

308: _col_ctr + + ; 

309: } 

3 10: inline void DoEndRow( void ) 

311: { 

312: if( _started_row ) { 

313: EndRowO; 

314: _started_row = FALSE; 

315: } 

316: } 



317: inline void DoEndResultSet( void ) 

318: { 

319: if( _started_set ) { 

320: DoEndRow(); // ensure we have closed the ro 
w 

321: EndResultSetO; 

322: _started_set = FALSE; 

323: } 

324: } 

325: inline void DoEndDoc( void ) 

326: { 

327: if( _printed.doc ){ 

328: // we have something on the document 

329: DoEndResultSetO; 

330: }else{ 

331: // we never generated any doc content 

332: if( ! _started.doc ) { 

333: DoBeginDoc( FALSE); 

334: } 

335: NoContentDocBodyO; 

336: } 

337: if( _started.doc ) { 

338: EndDocO; 



339: _started_doc = FALSE; 
340: } 
341: } 
342: }; 

[0171] This class serves as a base class for several other classes 
in the system (e.g., "HttpPresXML"). Once a connection is 
set up to the database and before a statement is exe- 
cuted, the system sets up the presentation layer so that 
when the statement begins executing and returning data, 
the system can stream that data back to the client through 
the presentation layer. The presentation layer, in turn, 
formats that data in an appropriate manner. 

[0172] The "HttpOStream" data member (line 117) provides ac- 
cess to an output stream, for returning data to the client. 
In order to track what character (collation) set should be 
applied, the class includes a "UTCollation" data member at 
line 118 (for use in cases where the outgoing character 
sets differs from that used by the database). The result set 
gets described before it is outputted, by data members at 
lines 124-127. For example, the "descriptor count" (line 
124) contains the number of columns that are going to be 
returned. Similarly, the row and column counter variables 
(lines 125-126) track the number of rows and columns as 



they are being outputted. Variables from lines 128-131 
indicate current context/position within the output docu- 
ment. 

[0173] Various in-line "put" methods are defined from lines 
135-163 for outputting data; as shown, these call into 
base "put" methods at lines 133-134. Parameter flags are 
employed to indicate when HTTP encoding ("HF_ENC" flag) 
and HTTP character set conversion ("HF.CONV" flag) is re- 
quired. By default, the "put" methods encode and convert 
data in an appropriate manner. However, some of the 
methods omit these flags for instances where encoding/ 
conversion is not desirable (e.g., outputting binary data). 
The current state of the presentation layer is available by 
invoking "HttpPresStatus" (line 186) and "PresStatusOk" 
(line 190). Since this class is a base class for several other 
classes, it defines an interface (i.e., virtual methods) at 
lines 260-275 for the methods that will be implemented 
by subclasses. Therefore, the "HTTPPress" class provides 
implementation only for the basic bookkeeping common 
to all different presentation types. 

[0174] 3. HTTP protocol 

[0175] | n the currently preferred embodiment, an "HttpProtocol" 
class may be declared as follows: 



[0176] 347: class HttpProtocol { 
348: private: 

349: HttpPhase .phase; // current phase of the req 
uest 

350: a_perf_tod _tod_connected; // time of day clien 
t connected 

351: a_perf_tod _tod_queued; // time of day request 
was queued 

352: a_perf_tod _tod_started; // time of day request 
was started 

353:// a_perf_tod _tod_finished; // time of day reques 

t was finished 

= time it is logged 

354: HttpString .method; 

355: HttpString _uri; 

356: HttpString .version; 

357: HttpHashTable .request; // table of headers in re 
quest 

358: HttpHashTable .response; // table of headers to 
send in response 

359: HttpHashTable .options; // table of options 
360: HttpString JastHeaderKey; // if value is continu 
ed on next 



361: // we need to know what t 

o 

append it to 

362: HttpStatus .status; 
363: HttpString _errorstr; 
364: /* 

365: _body_expected is whether or not we're expecting a 
body with this 
request. 

366: _body_expected_length is the expected length of th 
e body (based on 
HTTP headers). 

367: _body.length() is the actual length of the body recei 



ved so far. 


368 


*/ 


369 


HttpString _body; 


370 


a_bool _body_expected; 


371 


uint32 _body_expected_length; 


372 


HttpConnection * .connection; 


373 


HttpLogger * .logger; 


374 


a_bool _has_been_logged; 


375 


void SetDateHeaders( void ); 



376 


a_bool _send_headers; 


377 


a_bool _send_body; 


378 


a_bool _content_type_set; 


379 


friend class HttpRequest; 


380 


friend class HttpLogger; 


381 


public: 


382 


HttpProtocol( HttpConnection * connection, HttpLo 


gger * logger ); 


383 


~HttpProtocol(); 


384 


HttpPhase GetPhase( void ) { return( .phase ); } 


385 


a_perf_tod * GetTodConnected( void ) { return( 



&_tod_connected ); } 

386: a_perf_tod * GetTodQueued( void ) {return(&_t 
od.queued ); } 

387: a_perf_tod * GetTodStarted( void ) { return( &_to 

d.started ); 

} 



388 


void 


SetReqQueued( void ); 


389 


void 


SetReqStarted( void ); 


390 


void 


SetReqFinished( void ); 


391 


void 


SetOkToDelete( void ); 


392 


const HttpString * GetMethodQ const 


method; } 





393: const HttpString * GetUri() const { return &_uri; 
} 

394: const HttpString * GetVersion() const { return &_ 
version; } 

395: /* 

396: Request header methods 

397: */ 

398: void SetRequestHeader( const char *key, 

399: const HttpString *value ) { 

400: .request. Set( key, value->str(), value->length() ); 

401: JastHeaderKey.clearO; 

402: JastHeaderKey.append( key ); 

403: } 

404: void SetRequestHeader( const char *key, 

405: const char *value, 

406: const size_t len ) { 

407: .request. Set( key, value, len ); 

408: JastHeaderKey.clearO; 

409: JastHeaderKey.append( key ); 

410: } 

411: a_bool AppendRequestHeader( HttpString &valu 

e); 

412: HttpString * GetRequestHeader( const char * key ) 



{ 

413: return .request. Get( key ); 
414: } 

415: HttpString * GetRequestNextKey( const char * key 
){ 

416: return .request. GetNextKey( key ); 
417: } 
418: /* 

419: Response header methods 
420: */ 

421: void SetResponseHeader( const char * key, const 
HttpString * 
value ) 

422: { .response. Set( key, value->str(), value-> 

length() 

);} 

423: a_bool SetResponseHeader( const char * key, co 
nst char * value 

); 

424: HttpString * GetResponseHeader( const char * key 
) { return 

.response. Get( key ); } 

425: a_bool SetHTTPOption( char * optname, char * v 



alue ); 

426: HttpString * CetHTTPOption( char * optname ) { 
return( 

.options. Get( optname ) ); } 

427: a_bool ContentTypeSet( void ) const { return 

_content_type_set; } 

428: // .status methods 

429: void SetHttpStatus( HttpStatus status ) { .status 
= status; } 

430: void SetHttpStatus( HttpRequestState state ); 
431: HttpStatus GetHttpStatus( void ) const { return 
.status; } 

432: char * CetHttpStatus( char * buf, size.t len ); // 

get status 

string 

433: void SetErrorString( const char * str, const size.t 
len); 

434: const HttpString * GetErrorString( void ) const { 
return 

&_errorstr; } 

435: // .body methods 

436: HttpString * GetBody( void ) { return &_body; 
} 



437: a_bool GetBodyExpected( void ) const {return 
_body_expected; } 

438: uint32 GetBodyExpectedLength( void ) const { re 
turn 

_body_expected_length; } 

439: a_bool ParseRequest( const HttpString * request 

); 

440: a_bool ParseHeader( const HttpString * header ); 

441: a_bool ParseMethod( void ); 

442: a_bool ParseBodyLength( void ); 

443: a_bool SendHttpHeaders( HttpOStream * stream 

); 

444: a_bool SendHttpError( HttpOStream * stream ); 
445: void Writel_ogEntry( void ); 
446: void CleanUp( void ); 

447: a_bool ShouldSendBody( void ) const { return _se 
nd.body; } 

448: #if IPRODUCTION 
449: private: 

450: HttpString _resbody; 
451: public: 

452: HttpString * CetResBody( void ) { return &_resbod 

y;} 



453: #endif 
454: }; 

[0177] of interest, at lines 349-353, the class defines bookkeep- 
ing data members for tracking various information about 
the HTTP connection. Lines 354-356 include data mem- 
bers that track information about the URI itself. Hash ta- 
bles are established at lines 357-359 for hashing HTTP 
options and HTTP headers for the request and response. 
For example, the "request" hash table (line 357) gets pop- 
ulated at the beginning of handling the request. The "re- 
sponse" hash table (line 358) is initially populated by the 
system with default values, but then the invoked stored 
procedure may change values in the response (HTTP 
header) by invoking internal functions (e.g., "SetHTTP- 
HeaderField"). During output, the "BeginDoc" method (line 
260, from the "HttpPres" class) will begin outputting HTTP 
header information from the response hash table. Also of 
interest is the "options" hash table at line 359. Here, the 
stored procedure may set output options (e.g., whether or 
not to perform character set conversion in the output) for 
the HTTP response. 

[0178] 4. HTTP request 

[0179] | n the currently preferred embodiment, an "HttpRequest" 



class may be declared as follows: 

[0180] 459; c | ass HttpRequest : public RQBaseltem 

460: { 

461: HttpConnection * .connection; 

462: HttpProtocol * .protocol; 

463: HttpOStream * .stream; 

464: HttpService * .service; 

465: HttpService * .dservice; 

466: Database * _db; 

467: p.Connection .dbconnection; 

468: p.Worker .worker; 

469: a_bool .cancel; 

470: uint32 _uid; 

471: HttpString * .parms; 

472: HttpRequestState .state; 

473: HttpString .username; 

474: HttpString .password; 

475: HttpString .database; 

476: HttpString .service.name; 

477: HttpString .arguments; 

478: HttpString .url.path; 

479: HttpOrderedList .variables; 

480: a_bool .headers.sent; 



481: public: 

482: HttpRequest( HttpConnection * c, HttpProtocol * p, 
HttpOStream * 

s); 



483 
484 
485 



~HttpRequest(); 

p.Worker GetWorker() { return .worker; } 
HttpOrderedList * GetVariablesQ { return &_variabl 



es;} 






486 


a_bool 


Connected(){ return _dbconnection != N 


ULL; } 




487 


virtual void do_request(); 


488 


void 


CancelO; 


489 


void 


CleanUpO; 


490 


private: 




491 


a_bool 


ServiceExists( HttpString & name ); 


492 


a_bool 


DetermineServiceOptionsO; 


493 


a_bool 


ProcessAuthenticationO; 


494 


a_bool 


ProcessHttpAuthenticationO; 


495 


a_bool 


ProcessBasicAuthentication( const HttpS 



tring * 

base64_credentials ); 

496: a_bool DatabaseConnect( HttpString &charset ); 
497: void DatabaseDisconnectQ; 



498: a_bool ParseURIO; 

499: a_bool ParseArgs( HttpHashTable * argtable, Ht 
tpString * 
args ); 

500: a_bool ParseMultipartFormData( HttpHashTable 
* argtable, 

HttpString * args, char * boundary ); 

501: a_bool ParseArguments( HttpHashTable * arg_t 

able ); 

502: a_bool ParseBodyArguments( HttpHashTable * 
arg.table ); 

503: a_bool CetURLPathArguments( HttpHashTable * 
argtable ); 
504 



505 
506 
507 
508 
509 
510 
511 
512 
513 



a_bool DoDishRequestO; 
a_bool DoQueryRequestO; 
a_bool DoWSDLRequestO; 
a_bool ParseSoapRequestO; 

void RedirectToSecureO; 

void UpdateReceivedConnProperties( void ); 

void UpdateSentConnProperties( void ); 

void ReportSQLError( HttpPres * pres ); 

void SendHttpHeadersO; 

void MakeURK HttpString * host, HttpService 



vc, 

HttpString & uri ); 
514: }; 

[0181] This class derives from an "RQBaseltem" class, which is an 
internal system class that represents any sort of query or 
statement that is executed in the database engine. In par- 
ticular, the parent class represents any item that exists in 
the worker thread queue. Worker threads retrieve items 
from this request queue for execution in the database en- 
gine. Accordingly, incoming requests are placed in the re- 
quest queue so that they may be picked up by the forego- 
ing mechanism for execution in the database engine. At 
lines 461-465, the class defines various bookkeeping 
data members for tracking the connection, the protocol, 
and the output stream. At lines 464-465, two pointer 
variables are defined for tracking services. This provides 
an entry into the Web services table, for indicating the 
specific Web service being executed. At lines 466-467, 
the class defines pointers for the internal database and to 
the internal temporary connection (pseudo connection). 
Therefore, the actual connection to the database is kept at 
the level of an instantiated HttpRequest object. Lines 
473-478 include data members that store information 



parsed out of the request, including for example user- 
name and password used for the connection. Parameter 
information from the request is stored by the "params" 
data member (line 471). From the foregoing information, 
the system is able to log into the database and look up 
the requested Web service (using the service name). 

[0182] The "DoQueryRequest" method of the "HttpRequest" class 
may be implemented as follows. 

[0183] 5i9; a _bool HttpRequest::DoQueryRequest() 
520" J********************************** I 
521: { 

522: p.Connection dbc = _CurrentConnection; 

523: p.statement stmt = NULL; 

524: HttpPres * pres = NULL; 

525: p.cursor crsr = NULL; 

526: p.cursor reaLcrsr = NULL; 

527: p.stmt s = NULL; 

528: p_expr expr = NULL; 

529: a_bool variable; 

530: HttpOrderedList stmt.parms; 

531: #define C H EC K_C AN C E L() if( .cancel ) { goto cleanu 

p;} 

532: if( _service->GetServiceType() == HTTP_SERVICE_ 



SOAP ) { 

533: if( !ParseSoapRequest() ) { 

534: .state = REQU EST_ B A D_ R EQU EST ; 

535: return FALSE; 

536: } 

537: }else{ 

538: if( !GetURLPathArguments( &_variables ) ) { 
539: .state = REQU EST_BAD_REQU EST; 
540: return FALSE; 

541: } 

542: if( !ParseArguments( &_variables ) ) { 
543: .state = REQU EST_BAD_REQU EST; 
544: return FALSE; 

545: } 

546: if( !ParseBodyArguments( &_variables ) ) { 
547: .state = REQU EST_BAD_REQU EST; 
548: return FALSE; 

549: } 
550: } 

551: CHECK. CANCEL(); 
552: /* 

553: Set up the presentation layer 

554: */ 



555: switch( _service->GetServiceType() ) { 

556: case HTTP_SERVICE_XML: 

557: pres = New_HttpPresXML( .stream, dbc->db()-> 
collation ); 

558: break; 

559: case HTTP_SERVICE_HTML: 

560: pres = New_HttpPresHTML( .stream, 

561: dbc->db()->collation, 

562: (_parms == NULL 

563: ? .arguments : *_protocol->GetUri() ) 

564: ); 

565: break; 

566: case HTTP_SERVICE_RAW: 

567: pres = New_HttpPresRaw( .stream, dbc->db()-> 
collation ); 

568: break; 

569: case HTTP_SERVICE_SOAP: 

570: { 

571: HttpString nspace; 

572: HttpString opname; 

573: if(_dservice != NULL){ 

574: MakeURK (HttpString *)_protocol->_request.Get 
( "Host" ), 



_dservice, nspace ); 
575: }else{ 

576: MakeURK (HttpString *)_protocol->_request.Get 
( "Host" ), 
.service, nspace ); 
577: } 

578: GetOpName( _dservice, .service, opname ); 

579: pres = New_HttpPresSOAP( .stream, dbc->db()-> 

collation, &nspace, 

opname. c_str() ); 

580: } 

581: break; 

582: default: 

583: _assertD( FALSE); 

584: break; 

585: } 

586: dbc->pres = pres; 
587: /* 

588: Prepare the statement 
589: */ 

590: if(_parms == NULL){ 
591: // arbitrary query is allowed 

592: expr = an_ExprBuilder::GblBuilder.DB_Expr_str_len( 



.arguments. c_str(), (a_row_length) .arguments. Iength() ); 
593: }else{ 

594: // service specifies query 

595: expr = an_ExprBuilder::GblBuilder.DB_Expr_str_len( 
_parms->c_str() J 

(a_row_length)_parms->length() ); 
596: } 

597: if(expr == NULL){ 

598: .state = REQUEST_INTERNAL_ERROR; 

599: goto cleanup; 

600: } 

601: stmt = PrepareExpr( expr, GOAL.STATEMENT, NUL 
L, FALSE ); 

602: if( stmt == NULL){ 
603: DE_Free_expr( expr ); 
604: _assertD( SQLErr( dbc ) ); 
605: ReportSQLError( pres ); 
606: goto cleanup; 
607: } 

608: dbc->Setl_astStatement( expr ); 
609: DE_Free_expr( expr ); 

610: if( stmt->type != STMT_S ELECT && stmt->type ! = 
STMT.CALL ) { 



611: a_heap_ref ref; 

612: ref.mem = stmt; 

613: DV_Free_heap( &ref ); 

614: .state = REQU EST_BAD_REQU EST; 

615: goto cleanup; 

616: } 

617: if( !SetArgumentNames( &stmt_parms, stmt ) ) { 

618: a_heap_ref ref; 

619: ref.mem = stmt; 

620: DV_Free_heap( &ref ); 

621: .state = REQUEST_SQL_ERROR; 

622: goto cleanup; 

623: } 

624: stmt_parms.CopyValues( &_variables ); 

625: CHECK. CANCELO; // last change to check cancel 

before doing 

actual work 

626: /* 

627: Set up a cursor 
628: */ 

629: CreatePreparedStatement( dbc, stmt, &s ); 
630: _assertD( !SQLErr( dbc ) ); 
631: _assertD( s != NULL); 



632: dbi_describe_statement( s, DESCT.SELECTLIST, DE 
SC_NO_FLAGS, 0, 
&variable ); 

633: pres->SetArguments( &stmt_parms ); 

634: crsr = dbc->add_cursor( "http.cursor" ); 

635: crsr->stmt = s; 

636: DBOpenCursor( crsr, -1, CURSOR.READONLY, TRU 
E); 

637: if( crsr->ref != NULL && !SQLErr( dbc ) ) { 

638: // execute a procedure 

639: dbi_resume_procedure( crsr->ref, TRUE ); 

640: if( SQLErr( dbc ) ) { 

641: // proc.cursor has been closed and freed due to 
error 

642: crsr->proc_cursor = NULL; 

643: crsr->stmt = NULL; 

644: } 

645: } 

646: reaLcrsr = dbc->FindRealCursor( crsr, NULL, FALS 
E); 

647: .state = REQUEST.SUCCESS; 

648: if( reaLcrsr == NULL ) { 

649: // If statement was procedure call/batch, it might n 



ot have had 

650: // a result set. 

651: if( SQLErr( dbc ) ) { 

652: ReportSQLError( pres ); 

653: }else{ 

654: SendHttpHeadersO; 

655: } 

656: }else{ 

657: dbc->lock_cursor( reaLcrsr, TRUE ); 

658: dbi_row_descriptor( (p_db_cursor)real_crsr->db_cur 

sor.mem ); 

659: /* 

660: Update the status of the HTTP connection and se 

nd the headers 

661: out over the wire. 

662: */ 

663: _assertD( .state == REQUEST.SUCCESS ); 

664: SendHttpHeadersO; 

665: if( _protocol->ShouldSendBody() ) { 

666: DoFullFetch( reaLcrsr ); 

667: if( SQLErr( dbc ) ) { 

668: ReportSQLError( pres ); 

669: } 



670: switch( pres->GetPresStatus() ) { 

671: case PRES_OSTREAM_ERROR: 

672: .state = REQU EST_FAI LU RE; 

673: break; 

674: case PRES_NO_XML_USERTYPE: 

675: case PRES_NOT_XML_RESULTSET: 

676: .state = R EQU EST_ N OT_X M L ; 

677: break; 

678: } 

679: } 

680: dbc->unlock_cursor( reaLcrsr ); 

681: } 

682: DoCloseCursor( crsr ); 

683: dbc->drop_statement( s ); 

684: if( _protocol->ShouldSendBody() ) { 

685: dbc->pres->SendSuccessOrError( dbc, TRUE, TRUE 

); 

686: } 

687: #undef CHECK.CANCEL 

688: cleanup: 

689: if( pres != NULL ) { 

690: dbc->pres = NULL; 

691: delete pres; 



692: } 

693: if( .cancel ){ 

694: .state = REQUEST.CANCELED; 

695: } 

696: return .state == REQUEST.SUCCESS; 
697: } 

[0184] At the point that this method is invoked, the system has 
already connected to the database. After parsing the ar- 
guments of the request, the method sets up the presenta- 
tion layer. Lines 533-546 examine different parts of the 
incoming request. Beginning at line 555, the method in- 
cludes a "switch" statement to determine what type of 
service is actually involved in the incoming request. The 
"switch" statement includes different case arms for han- 
dling the different types of services (e.g., setting up the 
appropriate type of presentation layer). 

[0185] At line 588, the method begins preparing the statement 
for use in the database engine. In order to execute the 
query statement in the database engine, the system first 
creates an expression. The method creates this expres- 
sion at line 592 and "prepares" it at line 601. Beginning at 
line 627, the method sets up a database cursor. A sub- 
routine call to "dbi.describe.statement" (line 632) de- 



scribes the output to the presentation layer (e.g., how 
many columns will be in the output, and the like). In terms 
of actual execution, the stored procedure begins execu- 
tion upon invocation of the "dbi_resume_procedure" sub- 
routine, up to a point where a result set is about to be re- 
turned, as this allows the method to determine what in 
fact the result set is going to be. Thereafter, complete ex- 
ecution of the procedure may occur/resume, at line 639. 
After execution, the method checks for any error condi- 
tions. At line 654, the method instructs the presentation 
layer to dump/send the outgoing HTTP headers. Begin- 
ning at line 665, the method instructs the protocol 
(object) to start sending the HTTP body. Thereafter, the 
method may perform cleanup (e.g., cleanup database cur- 
sor) and is done. 

[0186] The "do.request" method of the "HttpRequest" class may 
be implemented as follows. 

[0187] 702: void HttpRequest::do_request() 
703" I**************************** I 
704: { 

705: UserDef *user = NULL; 
706: HttpString charset( 100 ); 
707: .worker = _CurrentWorker; 



708: _protocol->SetReqStarted(); 

709: #define CHECK_CANCEL() if( .cancel ) { goto finish; } 

710: CHECK. CANCEL(); 

711: if( !ParseURI()){ 

712: .state = REQU EST.BAD.REQU EST; 

713: goto finish; 

714: } 

715: if( !DatabaseConnect( charset ) ) { 

716: goto finish; 

717: } 

718: if( !DetermineServiceOptions() ) { 

719: goto finish; 

720: } 

721: /* 

722: Depending on the URI, the DISH service either acts I 
ike a WSDL 

723: service or a SOAP service. 

724: */ 

725: if( _service->GetServiceType() == HTTP.SERVICE. 
DISH ){ 

726: if( _arguments.eq( "wsdl" ) ) { 

727: /* 

728: "Fall through". The DISH service is generating WS 



DL, and will be 

729: treated as a WSDL service below. 
730: */ 
731: }else{ 
732: /* 

733: Set _service_name to the service specified in SOAP 
Action. 

734: SOAPAction URLs have the format "http://hostnam 

e/dbname/path" 

735: (quotes included). 

736: */ 

737: HttpString * action = _protocol->CetRequestHea 
der( "SOAPAction" 

); 

738: if( action != NULL){ 

739: HttpStrlStream stream( action ); 

740: int slash = 0; 

741: unsigned char c; 

742: while(TRUE){ 

743: if( !stream.get( c ) ) goto finish; 

744: if(c ==7'){ 

745: if( ++slash >= 4 ) break; 

746: } 



747: } 

748: _service_name.clear(); 

749: while(TRUE){ 

750: if( !stream.get( c ) ) goto finish; 

751: if(c == "") break; 

752: _service_name.append( c ); 

753: } 

754: _dservice = .service; 

755: if( IDetermineServiceOptionsO ) { 

756: goto finish; 

757: } 

758: /* 

759: DISH won't act as a proxy for anything other tha 
n SOAP 
services. 
760: */ 

761: if( _service->GetServiceType() != HTTP_SERVICE_S 
OAP){ 

762: goto finish; 
763: } 
764: } 
765: } 
766: } 



767: /* 

768: Secure connection 

769: */ 

770: if( _service->GetSecureRequired() && Lconnection 

->lsSecure() ) { 

771: Red i rectToSecu re() ; 

772: goto finish; 

773: } 

774: /* 

775: Authentication 

776: */ 

777: if( _service->GetAuthRequired() ) { 

778: if( !ProcessAuthentication() ) { 

779: goto finish; 

780: } 

781: } 

782: user = FindUserBylD( _uid ); 

783: if( user == NULL){ 

784: .state = REQUEST_INVALID_USER; 

785: goto finish; 

786: } 

787: _dbconnection->SetUser( user->GetSAUserName() 
, FALSE, TRUE); 



788: _dbconnection->set_user( user ); 

789: if( AuditingOn(_db)){ 

790: char address[80]; 

791: a_web_protocol_type proto = WEB.HTTP; 

792: _connection->GetRemoteMachineAddr( address, 

793: (int32)sizeof( address ) ); 

794: if( _connection->lsSecure() ) { 

795: proto = WEB.HTTPS; 

796: } 

797: AuditHttpConnection( user->GetSAUserName(), add 
ress, GetProtoStr( 
proto ), 

798: TRUE, _db ); 

799: } 

800: user->Release(); 

801: CHECK. CANCEL(); 

802: if( !CallLoginEnvironment( _dbconnection ) ) { 

803: DB_Exec_connect_failed_event_handler( _db, 

804: (char *)_dbconnection->_ew_static_user.str(), NU 
LL); 

805: .state = REQUEST_INVALID_AUTHENTICATION; 

806: goto finish; 

807: } 



808: if( Debug ) { 

809: DB_Message( IDS_ENG_USER_CONNECTED_TO_DAT 

ABASE_FROM_HTTP, 

810: _dbconnection->handle(), 

811: _dbconnection->get_user()->name, 

812: _db->_ro_alias, 

813: GetProtoStr( _connection->GetType() ) ); 

814: DBConnConverter *conv = _stream->getConverter() 

815: if(conv== NULL){ 
816: DB_Message( 

IDS_ENG_CHARSET_TRANSLATION_ENABLED_NOT_NEEDED 
_WITH_CONNID, 

817: _dbconnection->handle(), 
818: _db->cs_info->sybase_label ); 
819: }else{ 

820: const Charsetlnfo *cli_cs_info = 

821: UTLocale::GetCharsetlnfoFromAsaCID( conv->out 

bound().GetDestCid() 

); 

822: DB_Message( 

IDS_ENG_CHARSET_TRANSLATION_ENABLED_NEEDED_WIT 
H.CONNID, 



823: _dbconnection->handle(), 
824: _db->cs_info->sybase_label, 
825: cli_cs_info->sybase_label ); 
826: } 
827: } 

828: DB_Exec_system_event_handler( _dbconnection-> 
db(), _dbconnection, 
EVT.Connect ); 

829: ProcDebug::ConnectionStarted( _dbconnection ); 
830: /* 

831: Define special request header fields so user can acc 
ess them. 

832: BUGBUG: What do we set URI to when processing a 
SOAP request through 

833: a DISH service? For now, we're setting it to the URI 
of the 

834: DISH service, not the proxied SOAP service. 
835: */ 

836: _protocol->SetRequestHeader( "@HttpMethod", 
_protocol->GetMethod() ); 

837: _protocol->SetRequestHeader( "@HttpURr, _proto 
col->GetUri() ); 

838: _protocol->SetRequestHeader( "@HttpVersion", 



_protocol->GetVersion() ); 

839: UpdateReceivedConnPropertiesO; 

840: CHECK. CANCEL(); 

841: switch( _service->GetServiceType() ) { 

842: case HTTP_SERVICE_XML: 

843: case HTTP_SERVICE_HTML: 

844: case HTTP_SERVICE_RAW: 

845: case HTTP_SERVICE_SOAP: 

846: DoQueryRequestO; 

847: break; 

848: case HTTP_SERVICE_DISH: 

849: case HTTP_SERVICE_WSDL: 

850: DoWSDLRequestO; 

851: break; 

852: default: 

853: _assertD( FALSE); 

854: .state = REQUEST.INVALID.SERVICE; 

855: break; 

856: } 

857: #undef CHECK.CANCEL 

858: finish: 

859: DatabaseDisconnectO; 

860: if( .cancel ) { 



861: .state = REQUEST.CANCELED; 

862: } 

863: if( .state != REQUEST.SUCCESS ) { 
864: _protocol->SetHttpStatus( .state ); 
865: if( .state == REQUEST.SQL.ERROR ) { 
866: }else{ 

867: _protocol->SendHttpError( .stream ); 
868: } 
869: } 

870: _stream->flush(); 

871: UpdateSentConnPropertiesO; 

872: .worker = NULL; 

873: _connection->RequestFinished(); 

874: } 

[0188] After the incoming request gets picked up by a worker 
thread, this method is executed, for processing the re- 
quest from beginning to end. The method sets up the ini- 
tial database connection, and determines what options 
(parameters) the service is invoked with. As shown begin- 
ning at line 836, the method sets up the incoming HTTP 
request headers hash table. At line 846, the above men- 
tioned "DoQueryRequest" method is invoked for all ser- 
vices except for WSDL, which requires separate processing 



as indicated by the case arm at line 849. 
[0189] The "ParseURI" method of the "HttpRequest" class may be 

implemented as follows. 
[0190] 879: a_bool HttpRequest::ParseURI() 

881: { 

882: HttpStrlStream stream( _protocol->GetUri() ); 

883: unsigned char c; 

884: a_bool got_service = FALSE; 

885: _assertD( _database.length() == 0 ); 

886: _assertD( _service_name.length() == 0 ); 

887: _assertD( .arguments. Iength() == 0 ); 

888: if( !stream.get( c ) || c != '/'){ 

889: return FALSE; 

890: } 

891: if( _connection->DBNameProvided() ) { 

892: .database. append( _connection->GetDbName() ); 

893: }else{ 

894: while(TRUE){ 

895: if( !stream.get( c ) ) return TRUE; 

896: if(c == V ) break; 

897: if(c ==■?■){ 

898: got_service = TRUE; 



899: break; 
900: } 

901: .database. append( c ); 
902: } 
903: } 

904: if( !got_service ) { 

905: while(TRUE){ 

906: if( !stream.get( c ) ) return TRUE; 

907: if(c == 7') break; 

908: _service_name.append( c ); 

909: } 

910: } 

911: while( stream. get( c ) ) { 
912: .arguments. append( c ); 
913: } 

914: return TRUE; 
915: } 

[0191] This method parses URI information in a straightforward 
manner, including checking it for validity. For example, 
the method validates the database name, service name, 
and arguments, which are specified for the incoming re- 
quest. 

[0192] The "ServiceExists" method of the "HttpRequest" class may 



be implemented as follows. 
[0193] 920: a_bool HttpRequest::ServiceExists( HttpString & name 

) 

92 1" i**************************************************** 
I 

922: { 

923: a_bool result = FALSE; 

924: HttpService * svc; 

925: a_statement * stmt; 

926: p.Database db = .CurrentDB; 

927: svc = HttpService::Find( db, name.c_str() ); 

928: if( svc == NULL){ 

929: // The service by the full name does not exist... 

930: // need to split it up into <name>/<url> pieces 

931: char* str = name.c_str(); 

932: size_t len = name.length(); 

933: if(len==0){ 

934: return FALSE; 

935: } 

936: size.t split = len - 1; 

937: for( ; split > 0; split— ) { // Note: first char cannot 
be V 

938: if( str[split] = ='/'){ 



939: // split at this point 

940: HttpString tname( str, split ); 

941: svc = HttpService::Find( db, tname.c_str() ); 

942: if( svc != NULL){ 

943: if( svc->GetUrlPathType() != URL_PATH_OFF ) { 

944: // got [name=0..split-l]/[url=split+l..len-l] 

945: len = len - split - 1; 

946: if( len == 0 || svc->CetUrlPathType() == URL.PA 
TH.OFF ) { 

947: _url_path.set_empty(); 

948: }else{ 

949: _url_path.append( str+(split+l), len ); 

950: } 

951: name. resize( split ); 

952: break; 

953: }else{ 

954: svc->Release(); 

955: svc = NULL; 

956: } 

957: } 

958: } 

959: } 

960: if( split == 0 ) { 



961: return FALSE; 

962: } 

963: } 

964: if( svc != NULL){ 

965: _uid = svc->GetUid(); 

966: stmt = svc->LockStmt(); 

967: if( stmt != NULL) { 

968: p_expr stmtstr; 

969: uint32 len; 

970: stmtstr = Prep_to_str( NULL, stmt ); 

971: stmtstr = an_ExprBuilder::GblBuilder.DB_Find_ex 

pr( stmtstr, 

FALSE ); 

972: len = (uint32) stmtstr->v.str->length(); 

973: _parms = new HttpString( len + 1 ); 

974: { 

975: // Copy string to _parms 

976: DbStrlStream s( *stmtstr->v.str, _CurrentConnecti 
on ); 

977: s.get( (a_byte *) _parms->str(), (uint32) 
stmtstr->v.str->length() ); 

978: _parms->resize( len ); 

979: } 



980: DE_Free_expr( stmtstr ); 
981: } 

982: svc->UnlockStmt(); 
983: result = TRUE; 
984: } 

985: .service = svc; 
986: return result; 
987: } 

[0194] This method confirms that a corresponding service exists 
for the incoming request. At lines 937-959, a loop is es- 
tablished that tries to split up the URL (URI) path, for de- 
termining which service to use. These process steps are 
influenced by the URL path option, as shown. 

[0 1 95] 5_ httP presentation XML 

[0196] | n the currently preferred embodiment, an "HttpPresXML" 
(presentation for XML) class may be declared as follows: 

[0197] ioo7: class HttpPresXML : public HttpPres { 
1008: protected: 

1009: UTCollation * _col; // db's collation 
1010: a_bool _has_xml; // db has XML typeid / 
1011: uintl6 _xml_typeid; 

1012: a_bool _saw_xml; // we saw some XML col 
umns 



1013: a_bool _do_xml_formatting; // we need to d 
o the formatting 

1014: CacheCarver * _carver; 
1015: p_col_name _first_col; 

1016: p_col_name .current; // "cur" column i.e. co 
lumn[_cur_idx] 

1017: uintl6 _cur_idx; 
1018: public: 

1019: HttpPresXML( HttpOStream * ostream, UTCollatio 
n * col ); 

1020: virtual ~HttpPresXML(); 
1021: protected: 

1022: virtual void AddColumn( 

1023: char* table.name, 

1024: char* coln.name, 

1025: uintl6 coln.namelen, 

1026: uint32 asa_usertype ); 

1027: virtual void BeginDoc( void ); 

1028: virtual void BeginResultSet( void ); // start of res 

ult set 

(table) 

1029: virtual void BeginRow( void ); 
1030: virtual void BeginColumn( void ); 



1031: virtual void 


EndColumn( void ); 


1032: virtual void 


EndRow( void ); 


1033: virtual void 


EndResultSet( void ); // end result s 


et (table) 




1034: virtual void 


EndDoc( void ); 


1035: virtual void 


SendColumnValue( void * data, uint3 


2 len ); 




1036: virtual void 


SendColumnMultiPiece( void * data, u 


int32 len ); 




1037: virtual void 


SendSQLError( void * errmsg, size_t 1 


en ); 




1038: virtual void 


NoContentDocBody( void ); // called 


when doc has no 




content 




1039: }; 





[0198] a shown at line 1007, this class is derived from the previ- 
ously-described "HttpPres" class. Of interest is the 
"_do_xml_formatting" variable declared at line 1013. If the 
result set is already formatted as XML internally by the 
engine, then no additional formatting is done. Otherwise, 
the presentation layer formats the result set as XML. This 
allows the stored procedure (in the case of an XML ser- 
vice) to specify whether the XML should be formatted in- 



ternally by the engine (i.e., the engine directly returns an 
XML result set) or be formatted by the presentation layer. 
[0199] Beginning at line 1027, the class begins declaring the 

methods inherited from the base class ("HttpPres") that it 
will implement. In the case of the "HttpPresXML" class, 
these methods serve to make sure that the output is for- 
matted as a valid XML document. For example, the "Begin- 
Row" and "EndRow" methods may be implemented as fol- 
lows: 

[0200] 1165: void HttpPresXML::BeginRow( void ) 
1 166" /******************************** / 
1167: { 

1168: if( _do_xml_formatting ) { 
1169: PutAsc("<row" ); 
1170: .current = _first_col; 
1171: _cur_idx = 0; 
1172: } 
1173: } 

1195: void HttpPresXML::EndRow( void ) 
1 196" i******************************* i 
1197: { 

1198: if( _do_xml_formatting ) { 



1199: PutAsc(7>\n" ); 
1200: } 
1201: } 

[0201] As shown, these methods apply specific XML tags to row 
data (in instances where the presentation layer is respon- 
sible for XML formatting). 

[° 202 ] Similarly, the "BeginColumn" and "EndColumn" methods 
may be implemented as follows: 

[0203] ii74; V oid HttpPresXML::BeginColumn( void ) 
1 175" y*********************************** J 

1176: { 

1177: if( _do_xml_formatting ) { 
1178: for(; _cur_idx < _col_ctr; _cur_idx++ ) { 
1179: _assertD( .current != NULL ); 
1180: .current = _current->next; 
1181: } 

1182: _assertD( .current != NULL ); 
1183: PutAscC); 

1184: PutData( _current->name, _current->len, HF_COL 
NAME); 

1185: PutAsc("=\""); 
1186: } 
1187: } 



1188: void HttpPresXML::EndColumn( void ) 
1 189" i********************************* i 
1190: { 

1191: if( _do_xml_formatting ) { 
1192: PutAsc( ™ ); 
1193: } 
1194: } 

[0204] Here, the methods output, for example, the column name 
and length in a manner suitable for XML output. Imple- 
mentation methods servicing other types, such as raw and 
HTML, are implemented in a similar manner (i.e., out- 
putting the data in a manner required by the type's partic- 
ular format). 

[0205] while the invention is described in some detail with spe- 
cific reference to a single-preferred embodiment and cer- 
tain alternatives, there is no intent to limit the invention to 
that particular embodiment or those specific alternatives. 
For instance, although the currently preferred embodi- 
ment focuses on servicing HTTP requests, those skilled in 
the art will appreciate that the system may be easily mod- 
ified to support other similar protocols, such as FTP, tel- 
net, or the like. Clearly, it will be appreciated that modifi- 
cations may be made to the preferred embodiment with- 



out departing from the teachings of the present invention. 



